Developer Assistant v3.

45
Instruction Manual
developer.2empowerFM.com

Copyright © 2021

Table of Contents
1. Introduction
About this Manual
What is Developer Assistant?
What is Developer Assistant Advanced?
Support
Trial Period

2. Installation and Uninstallation in FileMaker Pro

FileMaker Version Required
Macintosh Installation and Uninstallation
Windows Installation and Uninstallation
Scripted Installation

3. Using Developer Assistant Standard Edition

The 2empowerFM Toolbox
What is the Toolbox?
Find Text
Evaluate FileMaker Calculations In Place
Move ListBox Lines
Getting Help

4. Using Developer Assistant Advanced Edition

Find All
Replace Text

5. Advanced Searches
Searching with Regular Expressions

6. Using Plug-in Functions

Developer Assistant Functions
What Are Plug-in Functions?
Where To Use Plug-in Functions
 Named Parameters
Shared Functions

7. About Dialog, Install License, and Preferences

The About 2empowerFM Dialog
Install License
Uninstall License
Preferences
Key-Combo Strings
Introduction
About this Manual
This manual is meant to be viewed on screen at whatever zoom level you're comfortable with. The table of
contents is clickable, can be shown on the side of most PDF viewers, and throughout the manual you will
find blue hyperlinks leading to related information. Y ou can view this manual on most tablets or laptops if
you prefer not to have it share the screen with FileMaker. W hile the manual can technically be printed, the
fonts may be smaller than you would prefer and there will be no page numbers for navigation. Y ou will lose
the ability to search the manual for keywords and click its hyperlinks. So we encourage you to save paper
and enjoy the full features of this manual on your favorite viewing device.

What is Developer Assistant?

Developer Assistant is a FileMaker® Pro database plug-in that was created to make your life as a FileMaker
developer easier. Its simple Toolbox dialog appears at the touch of a key to offer you functions that save
you time and automate repetitive tasks.

Summary of Features
Search for strings or regular expressions within all scripts.
Search within fields, tables, or the relationship graph in the Manage Database window.
Search in multi-line editable text or multi-line selectable lists within any FileMaker dialog.
Evaluate highlighted expressions in place instead of backtracking to Data Viewer.
On W indows, select a group of lines in a list and move them all to another location.

What is Developer Assistant Advanced?

Developer Assistant Advanced is an optional upgrade that adds the following features to Developer
Assistant:
Find a list of all matches in any type of search.
Replace text within script steps and multi-line editable text boxes.
Replace text of selected entries in the list of all found matches.
FileMaker is a trademark of FileMaker, Inc., registered in the U.S. and other countries.

Support
Visit support.2empowerFM.com to contact us with questions or suggestions about 2empowerFM products.
W hether you're reporting a bug, a typo, or you'd just like to ask for clarification on how to use a feature,
we're happy to help.

Trial Period
All 2empowerFM plug-ins come with a free 30-day trial period. If your trial period expires, please contact
support.2empowerFM.com to request an extension. The About 2empowerFM dialog will tell you how
much longer you have for each of your trials. See T he About 2empowerFM Dialog in T he About Dialog and
Preferences section for more information.
A pop-up dialog box will inform you when your trial has ended and the plug-in must be purchased. To
purchase, simply visit developer.2empowerFM.com
Installation and Uninstallation in FileMaker Pro
FileMaker Version Required
2empowerFM Developer Assistant v3.45 requires FileMaker 14 or later. Please use
2empowerFM Family v2.65 for FileMaker 13 and earlier.

Macintosh Installation and Uninstallation

1. Y ou must be running Macintosh OS X 10.9 (Mavericks) through 11 (Big Sur).
2. If you have many copies of FileMaker where you want to install plug-in files, see the Scripted
Installation section farther down. Otherwise, it's easiest to install on a few machines by following the
steps below.
3. In the 2empowerFM Developer Assistant v3.45.dmg file you downloaded (where you found this
manual), double click Install 2empowerFM Developer Assistant. If you don't see Install
2empowerFM Developer Assistant, try downloading the plug-in again and be sure to download the
Macintosh version instead of the W indows version.
4. The 2empowerFM installer will guide you through the remainder of the installation process.
The installer will automatically detect locations you can install to:

If you need to install to a custom location, such as to the Extensions folder of a FileMaker "Runtime"
solution, simply click in the Custom Location box and choose where you want to install.
The installer also makes sure 2empowerFM plug-ins you previously installed to all installation locations are
compatible with the one you're installing and offers to download updates for any that aren't compatible.

Uninstallation
Run the installer and choose Uninstall Plug-in or Uninstall All 2empowerFM Plug-ins on the page in the
above screenshot. Alternately, remove all plug-in files that begin with the name 2empowerFM from all of
the locations mentioned in the Manual Installation section below.

Manual Installation
For those running macOS 10.5 or earlier, or those who prefer to do a manual installation, please:
 download the Parent plug-in
and
download the Child plug-in
Double click each file to unzip it, then copy both unzipped plug-in files to one of the following locations:
Y ourself only for FileMaker Pro 9 and later:

~/Library/Application Support/FileMaker/Extensions

Y ourself only for a particular FileMaker Pro version (works only in FileMaker Pro 12 and later):

~/Library/Application Support/FileMaker/ <FileMaker Pro or FileMaker Pro Advanced> /

<version> /Extensions

All users of a particular FileMaker Pro version:

/Applications/ <FileMaker version> /Extensions

To reach one of the above locations, open Finder (the app you use to manage files and folders), then
hold Command and Shift , then press G . A Go to the folder dialog will appear. Paste the start of
one of the above locations in that dialog and click Go.

W hen installing plug-ins for FileMaker Pro, make sure all 2empowerFM plug-ins are in only
one of the above FM Pro locations or they may fail to work or even crash FileMaker if you
leave old plug-in versions installed. Using the Macintosh Installer is highly recommended as
it will ensure there are no duplicate copies of the plug-in in conflicting locations.

If you need help with manual installation, uninstallation, or with the installer, please contact us through
support.2empowerFM.com.

Windows Installation and Uninstallation

1. Make sure you are running W indows 2000 through W indows 10.
2. Make sure FileMaker is not open.
3. Open the Install folder inside the 2empowerFM Developer Assistant v3.45.zip file you downloaded
(the same file that contains this manual).
4. From the Install folder, run vcredist_x64 if you use 64-bit FileMaker, and run vcredist_x86 if you use
32-bit FileMaker. If you're not sure which FileMaker you use, run them both. Each will launch an
installer from Microsoft and ask that you reboot when done. These installers will add additional
Microsoft components necessary for Developer Assistant to run. FileMaker will not load the Developer
Assistant plug-in if these installers are not run, and it will not show you an error message or show the
plug-in FileMaker's list of plug-ins.
5. Make sure you have Microsoft .NET 4.x installed. FileMaker 13 and later automatically install it for
you. If you're running FileMaker 12 or earlier and you don't know if you have .NET 4.x, simply
download this file and run it. If .NET 4.x is missing, you will see 2empowerFM Family and
2empowerFM Developer Assistant in the Plug-Ins tab under FileMaker's Edit > Preferences...
menu, but neither plug-in will have a checkmark to its left and trying to add a checkmark will say the
plug-ins can't be enabled:

6. Copy the following files from the Install folder:

 2empowerFM.fmx64
and
2empowerFM_Developer_Assistant.fmx64

to one of the following locations:

Y ourself only for FileMaker Pro 9 and later:

\Users\ <your user name> \AppData\Local\FileMaker\Extensions

Y ourself only for a particular FileMaker Pro version (works only in FileMaker Pro 12 and later):

\Users\ <your user name> \AppData\Local\FileMaker\

<FileMaker Pro or FileMaker Pro Advanced> \ <version> \Extensions

All users of a particular FileMaker Pro version:

\Program Files \ <FileMaker version> \Extensions\

Make sure all 2empowerFM plug-ins are in only one of the above locations or they
may fail to work or even crash FileMaker if you leave old plug-in versions installed.
If 2empowerFM.fmx64 already exists in the location you are installing to, replace it
with the version that came with 2empowerFM_Developer_Assistant.fmx64. W hen
you start FileMaker, a dialog will tell you if other 2empowerFM plug-ins are not
compatible with the newer 2empowerFM.fmx64. In that case, please visit
www.2empowerFM.com to download and install the latest version of each plug-in
you are using.

Uninstallation
Remove all plug-in files that begin with the name 2empowerFM from each of the following locations:

\Users\ <your user name> \AppData\Local\FileMaker\Extensions

\Users\ <your user name> \AppData\Local\FileMaker\Extensions\

<FileMaker Pro or FileMaker Pro Advanced> \ <version> \Extensions

\Program Files\ <FileMaker version> \Extensions\

Scripted Installation
Installing a plug-in via FileMaker scripts is useful if you need to install a plug-in on many
machines at a company. If this is your first time installing the plug-in, we recommend that
you skip this section and use the Macintosh Installation and Uninstallation or the Windows
Installation and Uninstallation sections above.

FileMaker 12 and later provide an Install Plug-in File script step that can be used to install 2empowerFM
plug-in files embedded into FileMaker database Container fields. FileMaker versions before 12 could also
install plug-in files using a script, but only by using plug-in files placed in a special location on FileMaker
Server. Either method takes longer to set up than a typical install but can save time if you need to installl
or upgrade plug-ins on a number of FileMaker systems as soon as a database that needs the plug-ins is
opened.
 W hatever scripted method you use to install plug-in files, it's important to install all
2empowerFM Child plug-ins (such as 2empowerFM_Developer_Assistant) before installing
the one 2empowerFM Parent plug-in (2empowerFM_Developer_Assistant.fmplugin on Mac
or .fmx64 on W indows). The same Parent plug-in is used by all Child plug-ins, and all Child
plug-ins have longer names such as 2empowerFM_SQL_Runner or
2empowerFM_T ext_T oolkit.
The Parent plug-in is responsible for telling FileMaker which plug-in functions are available,
so if the Parent is installed before a Child plug-in, the Parent will not know it needs to make
the Child's plug-ins functions available to FileMaker. If you accidentally install the Parent
plug-in first, you can restart FileMaker after installing Child plug-ins to make their functions
available.

To install plug-ins in FileMaker 11 and earlier, search the internet for "FileMaker Server Guide to Updating
Plug-ins" to find FileMaker's official guide.
To install plug-ins in FileMaker 12 or later, use FileMaker 12's new Install Plug-in File script step as follows:
1. Create or open an existing FileMaker database in which you want to embed plug-in files to be
installed.
2. Open the File > Manage > Database... menu.
3. In the T ables tab, create a new table called update plugin.
4. In the Fields tab, create a new Container field to store the 2empowerFM parent plug-in and an
additional Container field to store each child plug-in you want to install. Y ou will need an additional
set of containers to store Macintosh and W indows plug-in versions if you need to install both:

5. Go to the update plugin layout that should have been automatically created when you created the
update plugin table.
6. Add all the Container fields you created to the update plugin layout.
7. Click the New Record button at the top of the update plugin layout to insert exactly one record. The
layout should contain 1 and only 1 record.
8. For Macintosh plug-ins, download plug-in files using links in the Manual Installation section. Unzip
the files you downloaded, then click and drag the 2empowerFM.fmplugin file to the Mac Parent
Plugin field you created on the FileMaker layout. Drag the
2empowerFM_Developer_Assistant.fmplugin file to the Mac Child Plugin field. If dragging files
isn't working, try right clicking a container, then choose Insert File...
9. For W indows plug-ins, download 2empowerFM Developer Assistant v3.45.zip and open its Install
folder. Drag the 2empowerFM.fmx64 file to the Windows Parent Plugin field you created on the
FileMaker layout. Drag the 2empowerFM_Developer_Assistant.fmx64 file to the Windows Child
Plugin field. If dragging files isn't working, try right clicking a container, then choose Insert File...
10. Create a FileMaker script to install plug-in files that looks something like this:
11. If you find that FileMaker tells you epVersion is an unknown function, you will need to run the two
Install Plug-in File script steps above without the If/End If around them.
12. Once the script is saved with a call to epVersion in it, if you load the script on another machine
where the plug-ins aren't installed, the If statement above will change to
If [<Function Missing> = "?"] which will still evaluate to true and so the Install Plug-in File script
steps will be run to install the plug-ins.
13. If you ever need to upgrade older plug-in files to newer ones, you can change the If statement above
to If [epVersion ≠ "<new version>"] where <new version> is whatever value epVersion returns in
the new version you want to install.
14. If you need to detect whether to install Macintosh or W indows plug-in files, add
If [Get ( SystemPlatform ) = 1] to your script and when true, install Macintosh plug-ins, otherwise
install W indows plug-ins.
Using Developer Assistant Standard Edition
The 2empowerFM Toolbox
Most of Developer Assistant's features are accessed using the Developer Assistant tab in the
2empowerFM T oolbox:

What is the Toolbox?

The 2empowerFM T oolbox is a small window that floats above FileMaker. It contains the buttons and
fields needed to provide access to various 2empowerFM plug-in features. It always contains the Utility tab,
plus additional tabs for various 2empowerFM plug-ins you have installed. The following T oolboxes on
W indows and Macintosh have an additional tab added for Developer Assistant:

Show Toolbox
To show the T oolbox:

On Macintosh, hold Command , Option , and Shift , then press X

On W indows, hold Ctrl , Alt , and Shift , then press X
Y ou can change what hotkey opens the T oolbox using 2empowerFM's Preferences.

Hide Toolbox
To hide the T oolbox:

On Macintosh, hold Command , Option , and Shift , then press X

On W indows, hold Ctrl , Alt , and Shift , then press X
Y ou can change what hotkey hides the T oolbox using 2empowerFM's Preferences. The hotkey that
hides the toolbox does not have to be the same hotkey that shows it.
Alternately, you can hide the toolbox with its close button:
On Macintosh, click the in the upper left of the T oolbox.
On W indows, click the in the upper right of the T oolbox.

Utility Tab
On the Utility tab of the 2empowerFM T oolbox:
 Click the Preferences button to bring up the 2empowerFM Preferences dialog.
Click the About 2empowerFM button to bring up the About 2empowerFM dialog.
Click the epVars button to display the values of all defined 2empowerFM variables.

Find Text
In the Developer Assistant tab of the T oolbox, you can use the buttons or the
button (part of Developer Assistant Advanced Edition) to find text in FileMaker Scripts,
Manage Database T ables and Fields, and the Manage Database T able Relationships Graph. Y ou can also
search Multi-Line T ext Boxes and Multi-Line Lists in any FileMaker dialog.

Find Text in Scripts

Developer Assistant can find text in FileMaker scripts. To do so, open the Script Workspace window using
the top menu item in FileMaker's Scripts menu (the top menu item has changed from ScriptMaker... to
Manage Scripts... in FileMaker 10 to Script Workspace... in FileMaker 14). The Script Workspace window
will now open (or Manage Scripts or Define Scripts will open in earlier FileMaker versions):

Or in FileMaker 10 through 13:

Open the 2empowerFM T oolbox, choose the Developer Assistant tab and make sure the pull-down menu
says :

If the pulldown says , click any script in the list of scripts and it should change to
. As an example, we'll type importantfunction in the box, then click the
button. After a few moments, the first script containing a match is opened and the script step containing
ImportantFunction() is highlighted:
 If you search and find a match, the T oolbox will continue to say
as long as the script you found a match in is focused. If you switch
focus to any other script, your search will change to . If you click
while the T oolbox says , your search will only
include the lines in the focused script.

W hen you click or , the search continues from before or after the script step
that is highlighted. If you move the highlight off of the step where the last match was found
and then click , the step you moved to becomes the new starting point of the
search in this particular script but does not change which script you started your search in.
The search will move on to the next script only after every match has been highlighted in the
current script without you manually changing the highlighted step. A search in most word
processors behaves the same way.
If you opened the current script by clicking but you move to the next script by clicking
, or vice versa, the current script will be set as the new starting script in your
search.

Search in a Single Script

To search in a single script instead of in all scripts, click on any of the script steps in the script you want to
search within. Y ou can also click the tab of the script you want to search in FileMaker 14 and later. The
2empowerFM T oolbox should change to show , at which point you may click a
search button such as .

If you want to search in the Script Workspace of FileMaker 14 or

later, you must click the script in the list of scripts, then click the tab of the script you
opened or click any of its script steps. Y ou can also double click the script in the list of
scripts to immediately focus its tab, though this has the side effect of keeping that script
open in a tab when you click a different script.
 Developer Assistant is able to search the text you see in the script editor
without opening each script in the script editor. This is done by
getting an XML representation of the entire script from FileMaker and translating that XML to
the same text you see in the script editor. Unlike the text in the script editor, the translated
script steps do not have long parameters truncated to fit the script editor and parameters
that aren't normally displayed in the script editor are appended to the end of the translated
step that is searched. Y ou can see how Developer Assistant has translated a particular step
in your script by doing a search to find that step and then looking at the translated step in
the Searched: box.
Full translation of script steps is a new feature in Developer Assistant 3.0. Earlier versions
did some minimal translation of XML when you performed a search, but only DA 3.0 and later
will fully translate all 167 (and growing) types of script step to let you search the exact same
text you see in the script editor. These translations are double checked against the text in
the script editor whenever that can be done without reducing search speed. If a
mistranslation is found, a dialog will request that you send us an error report so we can fix
the mistranslation for the next release.
There are a few cases where DA can't translate the XML completely. The most common case
is in steps that refer to a layout, like Go to Layout. These steps may show a value like
"My Layout" (table) but DA translates this as "My Layout" (<Invisible to DA>) . This is
because table is not included in the XML. The XML includes the layout name, and FileMaker
knows internally what primary table is associated with that layout name, but plug-ins like DA
have no way to find that table name.

Match Names of Script Steps

W hen you are searching in scripts, can be clicked to open the search menu which will contain an option
to . This option is checked by default, and it causes your search to include the
name of each script step.
For example, in the following script step:

the name of the step is Go to Field. Searching for go to with checked would find
this step, while searching with unchecked would not find this step.

can not be unchecked when Search in XML is active. The XML that
is searched has the name of the script step embedded in it and while it's technically possible
to strip that name out before searching, that doesn't seem like a feature that many XML
searchers would want. If we're wrong about that, send us a message at
support.dracoventions.com.

Match Names of Scripts

Script names are automatically included in your search unless Search in XML is active. W hen a script name
is found, its name gets highlighted and none of its script steps are highlighted:

Find Text in Fields and Tables

Developer Assistant can find text contained inside of FileMaker tables or fields. To do so, open the Manage
Database window using the File > Manage > Database... menu:
In the Manage Database window, click the Fields tab:

Open the 2empowerFM T oolbox, choose the Developer Assistant tab, and make sure the pull-down menu
says :

Type something to search for in the box, then click a search button such as . Y our search will be
done in the Fields tab of the Define Database dialog. If a field is found, it will be highlighted.
Y our search will include field metadata, which means it includes any text you type anywhere in the Field
Options dialogs such as My Data or My Message below:

Text, such as My Comment , entered in the Comment: field will also be included in the search:
 Y ou can add special comments to the Comment: field and use them to find the field again
later. Add a date so you know what fields you added each day or categorize fields using your
own special notation.

Match Names of Fields

W hen you are searching in Fields, can be clicked to open the search menu which will contain an option
to . This option is checked by default, and it causes your search to include the name of
each Field.
For example, in the following field:

the field name is MyField. Searching for MyField with checked would find this field,
while searching with unchecked would not find this field unless the field had the text
MyField somewhere in its metadata.

Find Text in Tables

In the Manage Database window, click the T ables tab:

Open the 2empowerFM T oolbox, choose the Developer Assistant tab, and make sure the pull-down menu
says :

Type something to search for in the box, then click a search button such as . Y our search will be
done in the T ables tab of the Define Database dialog. If a table is found, it will be highlighted.
T ables are mostly just containers of Fields. T ables have no additional metadata that you can search, so
when you find a match , it's either because the T able name itself matched your
search, or it's because a Field or Field metadata within the T able matched your search.

Match Names of Tables

W hen you are searching in T ables, can be clicked to open the search menu which will contain an option
to . This option is checked by default, and it causes your search to include the name of
each T able.

Find Tables in Relationships Graph

Developer Assistant can find tables in the table relationships graph:
Y ou can open the table relationships graph by first opening the Manage Database window using the File >
Manage > Database... menu. The Manage Database window will open:

In the Manage Database window, click the Relationships tab:

Open the 2empowerFM T oolbox, choose the Developer Assistant tab, and make sure the pull-down menu
says :

Type something to search for in the box, then click a search button such as . If any table
occurrence in the relationships graph has a name containing what you searched for, that table will be
highlighted in the graph. Click to search for the next matching table occurrence name.

Slow Relationships Graph Search

The only way to highlight tables in the relationships graph is to simulate typing the name of the table
within the relationships graph. As the table name is "typed" by Developer Assistant, you may notice
unrelated tables that begin with the same letters become briefly highlighted until the correct table is
selected. If it takes more than a second to highlight the correct table, the following progress bar will
appear:
Notice that Developer Assistant is trying to highlight a table called My Table W ith Spaces by typing only
the word my in the table relationships graph. This is because typing a space in the relationships graph is
ignored by FileMaker 12 and earlier, so there is no use typing anything more than my . If you have many
tables that start with the letters my , Developer Assistant must keep typing my until it happens to select
the one it was looking for. Each time the wrong table is selected, almost a second must pass before
FileMaker allows a new table to be typed in. This delay between typing each table can add up and make it
take a long time to highlight the correct table.
FileMaker 13 and later will respond to spaces typed in the relationships graph which often helps select the
correct table faster. Unfortunately, the W indows version of FileMaker 13 will not respond to typing most
non-letter characters such as - , _ , or any character your keyboard can't directly generate. This can make
some tables literally impossible to select by typing, and Developer Assistant will show an error after about
15 seconds of trying. W indows FileMaker 13 also appears to have a bug where it won't respond to the first
table typed after FileMaker is restarted, so you may notice a delay during your first table search.

For faster table search results in all FileMaker versions, avoid using spaces in table names
and avoid table names that begin with the name of another table, such as Table and Table2
(try Table1 and Table2 instead).
Y ou can achieve fast table search results regardless of spaces in table names by starting
each table name with a unique two-letter combination such as aa, ab, ac, and so on.

In a large relationships graph, FileMaker may respond slowly to typing table names. If
Developer Assistant is typing mytable and FileMaker delays too long after the t is typed,
the relationships graph may think when able is being typed that a table starting with a
should be highlighted. W hen this happens, Developer Assistant compensates by reducing the
number of letters it types and the progress bar will change to say it's typing 'myt' instead of
'mytable'. Unfortunately, typing fewer letters makes it more likely that additional tables will
begin with those letters and so it may take longer to highlight the correct table. If you don't
want to wait, press the Esc key to cancel the search and try again. Sometimes FileMaker
responds faster the second time, or you can try closing other programs that are using
significant amounts of memory or CPU.

Developer Assistant can't actually see the table names in the relationships graph, so if you
add or change a table name, you won't be able to find that table until you close the Manage
Database dialog and open it again. The table names Developer Assistant searches come from
a list that is only updated when Manage Database is closed.

Find Text in Multi-Line Text Boxes

Developer Assistant can find text in multi-line text boxes. A lot of FileMaker dialogs have multi-line text
boxes. Here are some examples:
To search in a multi-line text box, open the 2empowerFM T oolbox, choose the Developer Assistant tab,
then make sure the pull-down menu says :

Click in the multi-line text box you want to search and if Developer Assistant recognizes it as searchable,
the and buttons will become clickable (not greyed out). Click one of those
buttons to search in the multi-line text box.

Find Text in Multi-Line Lists

Developer Assistant can find text contained inside most multi-line lists. A lot of FileMaker dialogs have
multi-line lists, and they all look a little different, but they always have a scrollbar on the right (sometimes
hidden if the list is short) and they sometimes have a header with text labels at the top of multiple
columns. Here are some examples (the multi-line lists have been cut out of their parent windows in order to
fit more in the image):
W hen multi-line lists are split into multiple columns, such as the Field Name and T ype columns in the
middle-right list above, the search will include all visible text in all the columns. As you might notice,
FileMaker has added their own search box above a lot of the multi-line lists in FileMaker 14, but there are
still many they haven't gotten to, especially in older FileMaker versions.
To search in a multi-line list, open the 2empowerFM T oolbox, choose the Developer Assistant tab, then
make sure the pull-down menu says :

Click in the multi-line list you want to search and if Developer Assistant recognizes it as a searchable list,
the and buttons will become clickable (not greyed out). Click one of those
buttons to search the multi-line list.

Searching is usually much faster than searching in other ways, such

as , but the search only includes text that is visible in the multi-
line list. No metadata or other invisible text is searched.

W hen searching in multi-line lists that have collapsible groups of lines (such as when
searching ), lines that are hidden within a collapsed group will not
be searched.

The Search Menu

The search menu can be opened by clicking the magnifying glass icon and the menu will look something
like this:
Toolbox Always on Top
Put a check mark to the left of to always keep the 2empowerFM T oolbox above all
other windows. W ith checked, the Toolbox will also hide itself whenever FileMaker is
not foreground.

Search in XML
Put a check mark to the left of and your search will be performed in the XML representation
of certain kinds of searchable items such as script steps, tables, and fields. For example, in the following
script step:

If you search for exit without checked, your search will find a match in Exit Script [ ] :

If you search for exit with checked, you'll instead find a match in
<Step enable="True" id="103" name="Exit Script"></Step> which is the XML representation of the script
step:
Y ou can learn more about XML in the Replace in Scripts section.

Show Text Searched

Put a check mark to the left of and the 2empowerFM T oolbox will expand to show you
a Searched: box:

W henever you find a match, the Searched: box shows you exactly what you searched and where the match
was found in that search. The Searched: box is hidden by default when it will be clear what text was
searched by looking at the match that was highlighted in a FileMaker window. W hen it won't be clear what
text was searched, such as when Search in XML is checked, the Searched: box is automatically shown and
can not be hidden.

If you see the phrase <invisible to DA> in the Searched: box while searching scripts, it
means the text you would normally see in the script editor is not visible to Developer
Assistant. In other words, the XML representation of the script step that FileMaker provides
to DA simply doesn't contain the information needed to allow DA to construct that part of the
script step.
There are only two cases where this might happen: in the Go to Layout script step and in
the Go to Related Record script step when either refer to a layout in an external database.
In the script editor, you will sometimes see the name of the external database the layout
name in these script steps. In a DA search, the name of the external database that contains
a layout is never visible to DA, so you will see <invisible to DA> instead of the database
name.
A similar issue occurs when a script step shows the name of a script followed by the name of
an external database containing the script. In this case, DA can usually determine the
database name, unless that database is not yet opened, in which case the Searched: box
will display <file containing script is not open> . Y ou won't normally see that message more
than once because searching the script step triggers FileMaker to open the external database
it refers to such that next time you search that step the name of the external database will
be passed to DA.

Show Find All Results

Put a check mark to the left of to show the Find All results panel of the 2empowerFM
T oolbox:
The Find All results panel is also shown when you click , but if you close it and want to see it
again without performing a new search, use the menu item.

Show Advanced Features

controls whether Developer Assistant Advanced Edition features are displayed in
the 2empowerFM T oolbox. Advanced Edition features are represented by gold-tinted buttons such as
and .

If you decide not to purchase the Advanced Edition upgrade, you can uncheck to
hide features that aren't available in Standard Edition.

If you install a license for Advanced Edition, the menu item will disappear and
Advanced Edition features will always be visible.

Match Names of <thing being searched>

A menu item such as , , , etc, will
appear in this location whenever you have a control focused where it makes sense to include or exclude the
names of what you are searching. Details of what this menu item does can be found in the sections
describing each type of search, such as Find T ext in Scripts and Find T ext in Fields and T ables.

Match Case
Put a check mark to the left of and your search will only match strings that exactly match the
case of your search term. For example, if you search for apple with checked, strings containing
apple will be found, but Apple , applE , and aPpLe will not.

Text Matching Mode

Y ou may choose one of the following options to control how your search term will be matched:

Y our search will find words that contain your search term anywhere within the word. If you
search for tom you will match T om , atom , T ommy , and atomic .

Y our search will find only words that start with your search term. If you search for tom you will
match T om and T ommy , but you won't match atom or atomic .

Y our search will find only whole words that match your search term. If you search for tom you
will match T om , but you won't match T ommy , atom , or atomic .

Y our search will find only words that end with your search term. If you search for tom you will
match T om and atom , but you won't match T ommy or atomic .
 Y our search will be interpreted as a Perl-compatible Regular Expression. See the Advanced
Searches section for more information about Regular Expressions.

Find Missing References

W hen a script, table, field, layout, or other FileMaker object is deleted, references to the deleted item are
displayed using various labels such as <unknown> , <Table Missing> , <Field Missing> ,
<Function Missing> , and so on. Y ou can find any of these missing references by choosing the
search menu item and then clicking a search button such as .

Using fills the box with the search term (Missing References) .
Searching for (Missing References) triggers a special search that will find all kinds of deleted
and unknown references. If you manually type (Missing References) as a search term instead
of clicking , the special search will not be performed. Replace the entire
(Missing References) search term with something else to resume searching normally.

Search History
Each time you perform a search, your search term is added to the top of the section of the
search menu. Click any of those previous search terms to copy the term into the box.

Clear Search History

Click the search menu item to clear all entries from the section.

Evaluate FileMaker Calculations In Place

Copying a calculation over to FileMaker's Data Viewer so that you can evaluate it is a hassle and can waste
a lot of time when you have a lot of calculations to wade through. Developer Assistant addresses this
problem by letting you evaluate most calculations in the same text box the calculation is already typed into.
Developer Assistant can evaluate calculations in any FileMaker dialog containing an editable text box that is
more than one line tall. Click in the multi-line text box containing the calculation, then click in the
2empowerFM T oolbox to see the result of evaluating the text in that box.
Instead of evaluating all the text in the box, you can select only the text you want to evaluate and then
click . For example, if you highlight Get(SystemPlatform) in the following text box and click
, the result is 1 on Macintosh:

does not work in single-line text fields or in any kind of field in a FileMaker
database layout. Pretty much every single-line field that might contain a FileMaker
calculation also contains a Specify... button or similar that will open the calculation in a
multi-line editor where can be used.
Example: Use Evaluate to Debug a Running Script
Say a script isn't working. Y ou might turn on FileMaker's Script Debugger and run the script line by line, but
how do you tell when a calculation on a line isn't evaluating correctly? If you're stuck with only FileMaker's
Data Viewer, it's a real pain to copy a part of the calculation, close the Specify Calculation dialog, possibly
close the parent of the Specify Calculation dialog to unlock the Data Viewer, then add a new expression to
the Watch tab of Data Viewer, paste what you copied, then finally click Evaluate Now.
Then you have to open your original calculation again and find where you were, possibly copying another
piece of the calculation and doing the whole thing again. Madness!

Developer Assistant's button makes the process much faster:

In the above diagram, we've done the following:

1. Clicked in Script Debugger to open the Edit Script "ComboBox field entered" window.
2. Clicked in the line of the Edit Script window that matches the line being run in the Script
Debugger. This opens the "Set Variable" Options window.
3. Clicked in "Set Variable" Options to open the Specify Calculation window.
4. Scrolled down through the long calculation and highlighted epParam("objectName") - a part of the
calculation we think might be causing a problem.
5. Clicked in the 2empowerFM T oolbox.
6. And we instantly see that epParam("objectName") evaluates to "ComboBox" which means our
objectName parameter was passed in correctly.
7. Since that evaluation result was correct, we can continue to quickly highlight different parts of the
calculation and click to verify the whole calculation is working or to find the part that's not
working.

It's important to notice that as long as a script is running in Script Debugger, evaluating the
calculation is done in the context of that running script. For example, if no script were
running, epParam("objectName") would evaluate to "" because epParam gets its values
from whatever parameter is passed to a running script.

Multi-Selection Evaluate
Macintosh FileMaker 11 and later allow you to select multiple pieces of text at once by holding Command
as you drag the mouse cursor (represented in red ) over an additional piece of text:

W ith both epVar("MyVar" and ) selected, when you click the button it will evaluate the two
selections as one string, epVar("MyVar") , which will return the value of MyVar.

If you had evaluated the whole string, epVar("MyVar"; "MyValue") , epVar would have set the value of
MyVar to "MyValue" and returned an empty string "" .
Note that Microsoft W indows does not support selection of multiple pieces of text so this feature is not
available in W indows.

Move ListBox Lines

Many FileMaker dialogs contain ListBoxes with lines you can drag up and down, as indicated by an up/down
arrow at the left of each line:

In newer FileMaker versions, the up/down arrow has been removed from many dialogs, but the lines in those
dialogs can still be dragged up and down by clicking and dragging. In Macintosh FileMaker, you can select
more than one of these lines and drag them up or down together. Newer W indows FileMaker versions let you
do the same thing in some dialogs, but not in others.
2empowerFM T oolbox lets you move more than one line at a time in every W indows FileMaker dialog
containing lines that can be dragged. For example, you can select four lines to move in the T ables tab of
the Manage Database dialog, then click and choose Mark Selected List Lines from the menu:

Click a single line anywhere else in the list, then click and choose Move Marked Lines After Selection:
The four lines you marked are moved after the single line you selected (in this case, they're moved after the
Countries line):

The ability to move groups of lines will work in almost any list with lines you can drag up and down,
including lists of fields, tables, scripts, script steps, and so on.

Getting Help
Remember, you can always contact us by visiting support.dracoventions.com. W e're happy to help with
advice on how to use a feature you don't understand, listen to an idea for a new feature, or fix a bug in the
plug-in or a typo in the manual.
Using Developer Assistant Advanced Edition
Developer Assistant Advanced Edition is an optional upgrade to Developer Assistant Standard Edition
that unlocks the following advanced features:
Find a list of all matches in any type of search.
Replace and Replace & Find within multi-line editable text boxes and script steps.
Replace Chosen matches in the list of all matches.

Advanced Edition features are represented by gold-tinted buttons such as and

.

If you decide not to purchase the Advanced Edition upgrade, you can uncheck to
hide features that aren't available in Standard Edition.

Find All
Rather than click or to find one match at a time, Developer Assistant Advanced allows you
to click to find all matches in any type of search. These matches are displayed in a panel that
opens in the 2empowerFM T oolbox:

If you click and check in the search menu, the Searched: box will appear. After that,
you can single click any Find All result to show the full text of that result in the Searched: box:

If you double click the Find All result circled above, the ComboBox field modified script will be opened and
the script step on line 3 will be highlighted.
 Find All results will become unclickable (greyed out) when you don't have the window focused
that generated the results.
Find All results will disappear if you close the window that generated the results. If the Find
All results were generated by a search of all scripts, having any script window focused is
enough to keep the Find All results clickable, but the results will still disappear if you close
the Script Workspace (or Script Manager or Define Scripts in earlier FileMaker versions)
which is the window originally used to generate the results.

In most kinds of searches, Find All has no way to know when things have changed in the
window that generated the results. Therefore, if you find a match that refers to a script, then
move the script and double click the result that should open the script, it may take extra
time for Developer Assistant to search out where that script was moved to in the list of
scripts. Locating a Find All result that has moved is generally much faster than a whole new
search.
If you rename or delete the script a Find All result refers to, Developer Assistant will tell you
it can't find the script when you double click it in Find All results.

Find All in Multi-Line Text Boxes

Find All results in multi-line text boxes are unique in that they are updated as you change the text. Say
you find these results:

If you edit the text in the Expression: box, text in your Find All results updates as you type:
Replace Text
Developer Assistant Advanced allows you to replace text in multi-line text boxes as well as in script
searches.

W e would love to support replacements in other types of searches, such as in fields and
tables, but there is no way to instruct FileMaker to give us a copy of a field or table that we
can alter and send back to FileMaker to replace the original field or table. If the original field
or table were deleted to be replaced by the copy, everything in the database that referred to
the original table or field would refer to <unknown> instead of to the copy.

Replace in Multi-Line Text Boxes

Back in the Find T ext in Multi-Line T ext Boxes section you learned how to search for text in multi-line text
boxes. To replace text in these text boxes, first click anywhere in the text box you want to replace text in.
Open the 2empowerFM T oolbox, choose the Developer Assistant tab and change the pull-down
menu to :

Find some text in the multi-line text box using or , or you can manually highlight the text
you want to replace. Type something in the with: box, then click and dog changes to cat in
the text box in this example:
Replace in Scripts
FileMaker's script editor is easy to learn because all the standard script steps and their parameters can be
added and controlled via point and click. Y et, as many people become comfortable and proficient with the
script editor, they start to wish they could just edit the text of script steps with less pointing and clicking.
W ouldn't it be nice if that Set Variable [ $Var ] script step were just a string where it was easy to replace
$Var with $NewVar ? Developer Assistant Advanced can do that, but it's trickier than you might think.
The core problem with editing script text is that the text you see in the script editor does not always include
all the parameters of each script step. For example, in this Import Records step:

Specify import order is checked, which means we've specified which fields in MyFile.csv will be imported
into which fields in our database, but none of that information is displayed in the script step. In other
words, the string you see in the script editor, Import Records [ "MyFile.csv" ; Add; Mac roman ] , does not
include all the parameters that the Import Records script step is using, so there is no way to copy that
string to some external editor, change it, and paste it back without losing those invisible parameters.
In order to edit the text of the Import Records step, we need to convert it to a form of text that includes
all its invisible parameters. It turns out that when you copy a script step to the clipboard, it is copied in a
text format known as XML (Extensible Markup Language) that includes all its invisible parameters.
Developer Assistant lets you make replacements in this XML representation of a script step and return the
altered XML to FileMaker in a safe way.
XML is not the easiest language to read, but it's what FileMaker gives us to work with, so let's look at an
example.

Example 1: Replace in Go to Layout by Name

Open the script workspace (see instructions in the Find T ext in Scripts section if you're not sure how), then
open the 2empowerFM T oolbox, choose the Developer Assistant tab and change the pull-down
menu to :
Say we have a bunch of Go to Layout [ $$MyLayout ] script steps that we want to change to
Go to Layout [ $$NewLayout ] . W e type $$MyLayout in the box, type $$NewLayout in the with: box,
then click and we get this:

The text in the Searched: box is the XML representation of the Go to Layout [ $$MyLayout ] script step.
Developer Assistant has highlighted $$MyLayout in yellow indicating that is the text that will be replaced in
the XML representation.
How do you interpret that XML representation of the script step? Read through the examples in this
section and you should pick up on the important points, or you can search the net for XML primer to find
sites like this that give you the details about how XML is formatted.
In the above example, the layout name you wanted to replace is highlighted, and it's the only copy of that
layout name in the XML, so it must be the right thing to replace. In general, text strings are stored in XML
as <![CDATA[text string]]> or <Text>text string</Text> and it's usually safe to replace a text string in
XML.
Since it's clear you've found the correct match and text strings are usually safe to replace, click the
button and the script step changes to Go to Layout [ $$NewLayout ] in the script editor.
 W hy are and sometimes disabled when a script is focused?

The most common reason is that you have not yet clicked or . In a script
search, replacements are always performed on the highlighted text you see in the Searched:
box, and that box can only be set by first finding a match. This behavior differs from
replacements performed in multi-line text boxes where is never disabled and
whatever text you highlight in the text box gets replaced regardless of what the Searched:
box shows.

The other possible reason is that you clicked or in mode, then

switched to mode. In that case, the button will be disabled unless
you happened to perform your with Search in XML checked. remains
disabled because your match was found in the text displayed in the script editor, but
replacements can only be performed in the XML representation of a script step.
People have asked if we can support direct replacement of text displayed in the script editor,
but unfortunately the script editor steps have no standard format for their parameters which
makes it very difficult to replace within that text and transform the result back to the XML
representation that FileMaker needs to actually perform the replacement. It might be
possible to handle replace in the script editor text if unique replacement code was devised to
handle each of the 167 (and growing) different script steps, but it would take a long time to
implement, bugs would be likely, and it would increase the price of Developer Assistant.

Example 2: An XML Replacement Goes Wrong

It's not too hard to corrupt the XML representation of a script step by making a bad replacement.
Therefore, Developer Assistant performs the following steps during replacement to keep you safe:
1. Developer Assistant instructs FileMaker to give it the XML representation of the original script step
you want to replace.
2. Developer Assistant performs a replacement in the XML representation.
3. The original XML with replacement is sent back to FileMaker which transforms it into a new script
step that appears below the original script step.
4. Developer Assistant instructs FileMaker to give it the new XML representation of the new script
step.
5. If the new XML representation is identical to the original XML with replacement, then the
replacement was safe and the original script step is deleted.
6. If the new XML representation is different than the original XML with replacement, then the
original script step and new script step are both left in the script editor and an error like the
following is displayed:
In the error above, we tried to replace 93 with 0 (the two values circled in blue). The Beep script step
happens to have a unique id of 93 ( id="93" in the XML representation) and maybe we weren't paying
attention or didn't understand what we were replacing, so we tried to change that unique id 93 to 0. In Step
4, FileMaker was smart enough to notice that script step id="0" doesn't match the script step
name="Beep" (Beep script steps always have an id of 93), so FileMaker corrected the id, changing it back
to 93. In Step 6, DA saw FileMaker made that change to the XML, so DA showed the error above. The error
uses bold red to highlight that FileMaker changed 0 to 93 .
As the error says, the Beep script steps from before and after replacement were both left in the script
editor and it's up to you to decide which one to keep. In this case, FileMaker corrected the id="93" attribute
so both Beep script steps will be identical and it doesn't matter which you delete. When in doubt, always
delete the lower script step and keep the original upper script step.

Example 3: An XML Replacement Error you can Ignore

In this case, we changed $$MyLayout to $$NewLayout (each circled in blue) in a Go to Layout script step,
but for some reason FileMaker decided to add id="0" name="" to the altered XML. If you look in the
script editor at the new script step it won't look any different than the original script step and both script
steps will behave identically if the script is run:

After some investigation, we discovered that in the script editor, if you change a script step from
Go to Layout [ $$MyLayout ] to Go to Layout [ original layout ] , it leaves the XML representation of the
script step set to <Layout><Calculation><![CDATA[$$MyLayout]]></Calculation></Layout> without the
id="0" name="" attributes. If you copy and paste that script step, FileMaker adds the id="0" name=""
attributes. The script step behaves identically whether or not those attributes are there, and it makes sense
that if the attributes are missing, FileMaker will assume an id of 0 and a blank name as default values, so
this oddity is something you can ignore.

This script step is also interesting because even though it displays Go to Layout [ original layout ] in the
script editor, it still contains a reference to $$MyLayout in its XML representation. That's because the
script step was originally Go to Layout [ $$MyLayout ] but $$MyLayout was changed to original layout
without deleting the $$MyLayout parameter. If you change the step back to Layout Name by
calculation...:

$$MyLayout will appear by default in the Specify Calculation window because that value still exists in the
XML representation of the script step.

Here's an interesting theory: The fact that FileMaker remembers whether a script step has
<Layout> or <Layout id="0" name=""> as its XML representation seems to imply that
FileMaker actually stores script steps as XML internally, or as something very similar to XML.
If FileMaker were storing the layout id and layout name in some other structure, it would
always convert that other structure to <Layout id="0" name=""> instead of sometimes
converting to <Layout> .

Example 4: An XML Replacement Results in an Invalid Script Step

In this example, we tried to replace step with stage , expecting to replace text strings that refer to "steps"
in a process with text strings that refer to "stages" in a process:
W e didn't notice that we had matched <Step , which is not a text string, and changing it to <stage
results in a completely invalid script step. In XML terms, <Step enable="True" id="93" name="Beep"> is
the start of an XML element called Step. Every script step has a Step element that begins with <Step ...>
and ends with </Step> . Between <Step ...> and </Step> you may find other XML elements and text
strings representing each of the parameters of the script step. In the case of the Beep script step, it has
no parameters, so its Step element contains no other XML elements or text strings.

Replace & Find

Clicking is the same as clicking followed by .

Replace Chosen
appears only after performing a search in mode:

is disabled above because no lines have been chosen in the Find All results. Once you
choose at least one line, you can click in order to replace the chosen Find All results:
Don't worry, always asks for confirmation before performing replacements:

To replace the same text in many scripts, you can switch to mode, make sure the
list of scripts is focused, then click to find the first match. If you want to replace that
match, click , otherwise click to move on to the next match.

Instead of using and , you can click . In the list of Find

All results, select each match you want to replace, then click . This method of
replacement will open each script to perform the replacement starting with the top selected
Find All result and moving down.
Replacement in scripts always works one script step at a time because if you copy an entire
script, change it, paste it back, then delete the old script, all references to the old script are
broken.

If encounters an error during replacement, replacement is aborted at the Find

All result line that caused the error. The lines that were successfully replaced will have their
yellow highlighted text updated to contain the replaced text. The first selected line that was
not updated is the line that caused the error. Selected lines below the line that caused the
error will not have replacements attempted and will not have their text updated.
Advanced Searches
Searching with Regular Expressions
W hen you check the checkbox in the search menu, all of your Developer Assistant
searches will be done using Regular Expressions instead of standard text. Regular expressions can be
used to search for almost any recognizable pattern of text, such as phone numbers, emails, functions that
take exactly 3 parameters, and so on.
In Developer Assistant Advanced, regular expressions can also be used for replacements that move groups
of matched characters around to new locations.

Regular Expressions Overview

To fully understand regular expressions takes a long time, and there is a lot to learn about them because
they are so powerful, but this section will give you a basic understanding of what regular expressions are
and how to use simple regular expressions to find things like all words that start with Chris .
Basically, a regular expression is a series of symbols used to match patterns of characters in a string.
Regular expressions allow you to use advanced pattern matching to find almost any string you can
imagine. Y ou've probably already used simple pattern matching when doing searches in various
applications or internet search engines. A common pattern matching symbol is the * character, which is
often used to match zero or more characters. W hen performing a Find in FileMaker, if you search for

Chris*

in a FileMaker field, FileMaker will find fields with matching values like Chris , Christy , and Christopher
because the * symbol matches zero or more characters that follow Chris .

Instead of just * , Regular expressions use 14 different pattern matching symbols: . , * , + , ? , [ , ] , | ,

( , ) , { , } , ^ , $ , \ . W e'll cover many of these symbols in the remainder of this section.

The meaning of * in a regular expression is slightly different from how we used it in the simple example
above. Instead of matching zero or more of any character, a regular expression * matches zero or more
of whatever character it follows.

So, to find all words that start with Chris , your regular expression would need to include another special
pattern matching symbol, the dot . character:

Chris . *

The . character matches any character except a line break. So when you add .* to a regular expression,
you're asking to match any character (except a line break) zero or more times.

Finding a Phone Number

Besides using * to match a character zero or more times, you can also use + to match a character one or
more times, ? to match a character zero or one time, or {#} to match a character an exact # of times
(like {3} for 3 times). For example, this regular expression:

\([0-9]{3}\) [0-9]{3}-[0-9]{4}

will match a string that contains a phone number like (123) 456-7890 in the following format:

1. A left parenthesis: \(
2. followed by 3 digits (0 through 9): [0-9]{3}
3. followed by a right parenthesis: \)
 4. followed by a space
5. followed by 3 digits: [0-9]{3}
6. followed by a dash: -
7. followed by 4 digits: [0-9]{4}
Anything placed within square brackets is considered to be a character class that matches a particular set
of characters. In the example above, the character class [0-9] will match any character between 0 and 9.

Notice that in the phone number expression, the ( and ) parenthesis are escaped, meaning they have a
backslash \ character added before them. This is because parenthesis are one of the 14 pattern matching
symbols we mentioned earlier that have a special meaning in a regular expression. To match one of these
special characters in your string, you must escape it with a backslash: \. , \* , \+ , \? , \[ , \] , \| , \( , \) ,
\{ , \} , \^ , \$ , \\ . Technically, ] doesn't always need to be escaped, but escaping it doesn't hurt.

Line Breaks
W hen editing text, if you press the Enter key on the keyboard, a line break is inserted and the cursor
moves to the next line and to the left edge of the text. Each line break in the text is actually represented
by invisible characters that you can find or replace using a regular expression.

On OS X, find a line break using: \r

On W indows, find a line break using: \r\n

W indows uses two invisible characters at the end of each line and OS X uses just one. If you
find or replace just \r or just \n on W indows, the text may behave strangely, so always use
\r\n together on W indows.

If you're curious about line breaks, here's a brief history:

\r represents character code 13 which is known as a Carriage Return, aka CR. \n
represents character code 10 which is known as a Line Feed, aka LF. On old PCs and
terminals, a CR would move the text cursor to the left edge of the screen without changing
its line number, while an LF would move the cursor down a line without changing its
horizontal position. Typing the Enter key would insert both a CR and an LF to move the
cursor down a line and to the left edge.
Most modern OS X and Unix apps use just \n for each line break, but FileMaker standardized
on \r back when that was the norm in OS 9 and earlier.

Curly Quotes
Curly quotes are also known as smart quotes or quotes that look different on the left and the right:

“” ‘’
Straight quotes look the same on the left and right because the exact same quote character is used for
both left and right quotes:

"" ''
W hen you type quotes in Developer Assistant's box, you always get straight quotes. To make it easier
to find curly quotes in what you're searching, when is not checked, straight double
quotes are automatically matched to all forms of curly double quotes in whatever you are searching, and
straight single quotes are also matched to all forms of curly single quotes.
 W hen is checked, straight quotes are not automatically matched to curly
quotes.
If you would like to match both straight double quotes and all forms of curly double quotes
in a search, use the following character class:
[\"\u201C\u201D\u201E\u201F]
To match both straight single quotes and all forms of curly single quotes, use the following
character class:
['\u2018\u2019]

Finding a 3-Parameter Function

W hat if you remember writing a function in a script, but you don't remember what the function was called,
only that it had exactly 3 parameters? Y ou can search for all functions with 3 parameters using the following
regular expression:

[a-zA-Z]+\([^;)]+; *[^;)]+; *[^;)]+\)

This regular expression matches:

1. One or more characters from a through z or A through Z : [a-zA-Z]+

2. followed by a left parenthesis: \(
3. followed by one or more characters that are not semi-colons or right parenthesis: [^;)]+
4. followed by a semi-colon and zero or more spaces: ; *
5. followed by one or more characters that are not semi-colons or right parenthesis: [^;)]+
6. followed by a semi-colon and zero or more spaces: ; *
7. followed by one or more characters that are not semi-colons or right parenthesis: [^;)]+
8. followed by a right parenthesis that ends the function: \)

In the example above, the character class [^;)] begins with a special ^ character that tells the
character class to match any character that is not one of the characters following the ^ . If you actually
want to match a ^ character in the character class, you can escape it as \^ or you can make sure it's not
the first character in the character class.
Y ou might have also noticed that we did not escape the right parenthesis like we did in the phone number
example. W ithin a character class, only characters that have special meaning within the character class
( ^ , ] , - and \ ) need to be escaped. For example, you would need to escape a right square bracket to
include it in a character class: [\]] . Technically ] doesn't need to be escaped in []] or [^]] , but
escaping it doesn't hurt.
W hen your regular expression starts to get a little complicated, like the one above, you'll often find that it
matches things you did not intend it to match. For example, the regular expression above matches some
functions that don't take 3 parameters, like:

Case( x > 0; Left(y; x) ; x < 0; Right(y; -x) )

Although none of the functions above takes 3 parameters, the Case( x > 0; Left(y; x) portion of the string
actually does match the particular regular expression we used for our search.
It's possible to make a much more complicated regular expression to avoid finding matches we did not
intend to find, but it's usually easier to just understand why a false match sometimes occurs and to keep
searching till you find the particular function you're looking for.

Swap Day and Month in Dates

W hen writing dates, in some areas of the world, you put the month first, in other places you put the day
first. Regular expressions let you swap groups of matched text, such as the day and month number, using
backreferences. The following regular expression will match a date and create a group containing the
day and month:
 ([0-9]{1,2}) - ([0-9]{1,2}) - ([0-9]{4})

The ( and ) pattern matching symbols begin and end a group, and that group can be referred to in a
replacement string as $1 for the first group, $2 for the second group, and so on. To swap the day and
month you would put $2-$1-$3 in the with: box:

Click then and 1-23-2015 changes to 23-1-2015 .

Rather than using numbered groups, you can give your groups names using
(?<day>[0-9]{1,2}) - (?<month>[0-9]{1,2}) - (?<year>[0-9]{4}) . Refer back to those
names using $+{month}-$+{day}-$+{year}

More Information
2empowerFM regular expressions are based on a well-tested, third-party library that provides regular
expressions almost identical to Perl regular expressions, one of the oldest and most widely-used form of
regular expressions. There is a lot more you can learn about Perl regular expressions online, such as
additional character classes, escape sequences, extended patterns, and so on.
Try searching online for "perl regex" or read the original Perl regular expression manual here. Y ou can also
find regular expression tutorials, searchable libraries of regular expressions, and there are even regular
expression builders available that make it easier to construct regular expressions and see what each part of
the expression does. W e don't endorse or have any affiliation with any of the links to external sites
provided above - they're merely some of the results we found when searching for examples.
Using Plug-in Functions
Developer Assistant Functions
Unlike other plug-ins in the 2empowerFM Family, Developer Assistant does not provide any of its features
through the use of plug-in functions. However, you may still use plug-in functions to access features
shared by all plug-ins in the 2empowerFM family, such as reading and writing variables, setting plug-in
configuration options, and so on.

What Are Plug-in Functions?

Plug-in functions allow you to access features of the 2empowerFM plug-ins by typing various functions
directly into a field within a FileMaker dialog box. These functions always begin with the letters ep followed
by a function name, then function parameters in round brackets. Some examples of plug-in functions:

epParam("paramName")
epVar("variableName"; "variableValue")
epConfig("setErrorCapture=On")

Where To Use Plug-in Functions

Plug-in functions can be put anywhere a standard FileMaker function like If() or Trim() can be put. Plug-in
functions are usually placed in the Specify Calculation dialog opened by editing certain FileMaker script
steps or field-validation calculations. A common place to call a plug-in function within a FileMaker script is in
the Value: calculation of a Set Variable script step:

If you've never worked with FileMaker scripts before, you can create a script as follows:
Click the Scripts menu in FileMaker, then click the Manage Scripts... sub-menu.
Click the New button in the lower left. A new Edit Script window with an empty script script called
"New Script" will open.
In the example pictured above, a Set Variable script step was inserted by choosing Set Variable from the
list of script steps on the left side of the Edit Script window. Highlight the Set Variable script step that you
inserted and you will see a Specify... button appear in the lower right of the Edit Script window. Click that
Specify... button to bring up the "Set Variable" Options window shown above.
Based on what's been typed into the "Set Variable" Options window shown above, the script step will set
the $result variable to the value returned by calling epParam("MyParam") . The value placed in the $result
variable can be used later in the script, or simply ignored if a plug-in function doesn't return a value you
need to use anywhere.
 Y ou can click the Specify... button to the right of theValue: box to open the larger Specify
Calculation dialog to make it easier to call longer plug-in functions.

Again, plug-in functions can appear in any FileMaker calculation, such as in an Optional script parameter:
calculation:

Instead of typing in the function's name, you can get a list of available plug-in functions in any Specify
Calculation dialog by clicking the arrow to the right of the View: pulldown menu and choosing External
functions:

Once you have chosen to view External functions, you may need to scroll up or down to find the section for
2empowerFM:
Double click on any plug-in function in the list to insert it into your calculation. For example, say you
double click a function called epPersonCreate and it inserts the following into your calculation:

epPersonCreate( name {; gender } {; "params" } )

/*
This function does not actually exist - it is only an example.
name : Name of the person to create.
gender : "F" for female or "M" for male.
"params" : position=Stand|Sit, height=6 [feet tall]
*/

epPersonCreate is the name of the function, followed by function parameters in ( round brackets ) . The
{ curly brackets } around {; gender } and {; "params" } tell you those parameters are optional and can
be left out.

The function is followed by comments between /* and */ . The comments contain a brief explanation of
what each parameter means. FileMaker will ignore anything you put between /* and */ so you are free to
add additional comments or delete the comments entirely.

The comments tell you that gender can be given a value of "F" for female or "M" for male. Since gender is
also an optional parameter, you can assume the first value ( "F" ) is the value that will be used if you do not
provide the gender parameter.

"params" appears in " double quotes " because it is a Named Parameter string that may contain a value
for position (Stand or Sit) and/or a value for height (number of feet tall). Again, the first value after each
parameter (Stand or 6) is the default value if you don't include that parameter.
Named Parameters are discussed in detail in the next section, but here are some ways you can call
epPersonCreate:

epPersonCreate( "Joe" ; "M" ; "position='Stand'; height='5.5' " )

epPersonCreate( "Bob" ; "M" ; "position='Sit' " ) // Bob will be the default 6 feet tall
epPersonCreate( "Mary" ) // Mary will be 6 feet tall and standing

Named Parameters
Named Parameters are always contained in a string of text enclosed in double quotes: "string of text" .
The following string contains three Named Parameters:

" name = 'Joe Bob' ; age = '21' ; height = '5.8' "

name is the name of the first parameter. It is followed by an equal sign ( = ) and then its value (Joe Bob)
in ' single quotes ' .
age is the name of the second parameter, and its value is 21
height is the name of the third parameter, and its value is 5.8
 If you are familiar with using FileMaker's
Evaluate("Let([" & $paramString & "]; paramName)") syntax to get the value of
paramName in $paramString, you can format Named Parameters in the same way you
format $paramString.

Compare the following two function calls, the first using Ordered Parameters and the second using
Named Parameters:

epPersonCreate("Joe Bob"; 21; 5.8)

epPersonCreate("name = 'Joe Bob'; age = '21'; height = '5.8' ")

The function called with Ordered Parameters is hard to understand because 21; 5.8 could mean anything,
but Named Parameters make the meaning clear.
Named Parameters are flexible:
Y ou can omit parameters that have a default value.
Y ou can write parameters in any order:
"name = 'Joe'; age = '21' " is the same as "age = '21'; name = 'Joe' "
Y ou can omit the spaces around equals ( = ) and omit semi-colons ( ; ) between parameters:
" name='Joe' age='21' "
Y ou can omit the single quotes if the value doesn't have a space in it:
"name=Joe age=21"
Extra spaces are ignored:
"age=21" is the same as " age = 21 "
Y ou can use double quotes instead of single quotes:
" name=\"Joe Bob\" "

Notice that we put a double quote character inside a double quoted string by
adding a backslash before the double quote:
\"
Adding the backslash is known as escaping the double quote and is necessary to
distinguish a double quote character within the string from the double quote that
ends the string.

Y ou can (and should) use FileMaker's Quote function:

" name=" & Quote("Joe Bob")
 Using FileMaker's Quote() function is the recommended method of providing a
Named Parameter value. For easy reading of your parameters, format them like
this:
epPersonCreate(
" name=" & Quote( "Joe Bob" ) &
" age=" & Quote( $ageVariable ) &
" gender=" & Quote( MyTable::GenderField ) &
" height=" & Quote( "60\"" )
)
In the example above, " name=" returns the string name= , Quote( "Joe Bob" )
returns the string "Joe Bob" , and & joins the two strings together to form
name="Joe Bob" . Using Quote() around all values is a good habit because it's
critical to use Quote() around variables like $ageVariable and
MyTable::GenderField because they could contain characters that need to be
escaped.
Quote() also protects you from mistakes like forgetting to add a space before a
parameter name. Even with no spaces, a Named Parameter string like
name="Joe Bob"age="20"gender="M"height="60\"" will work correctly thanks to
the quotes.

Named Parameters are case sensitive. That means name=Joe is not the same as
Name=Joe . Also, doSomething=Yes is not the same as doSomething=yes .
Always wrap FileMaker fields and variables in Quote() , as in
"namedParam=" & Quote($variable) , because you never know when a field or variable might
contain a double quote, a line break, or some other character that needs to be escaped. Even
integer variables that don't normally need Quote() often end up containing values you don't
expect, such as "" , which will create a syntax error in your Named Parameter string if you
don't use Quote() . See the FileMaker help file entry on Quote() for more information.

Many 2empowerFM functions take Named Parameters, and some return Named Parameters. W hen
Named Parameters are returned, use the epParam function to get the value of any Named Parameter in
the string.

Shared Functions
The functions described in this section are not specific to the unique features offered by the 2empowerFM
Developer Assistant plug-in. These functions are shared amongst every plug-in in the 2empowerFM family of
plug-ins.

epParam
epParam( paramName {; paramsString } {; "optionalParams" } )

epParam returns the value of a Named Parameter contained in paramsString.

paramName is the name of the Named Parameter to return.
paramsString is a string containing Named Parameters. If paramsString is omitted, the value of
Get(ScriptParameter) will be used.
"optionalParams" may contain the following Named Parameter:
exists: Instead of returning the value of paramName or an empty string ( "" ) if paramName does
not exist, epParam will return 1 (true) if paramName exists, or 0 (false) otherwise.

Examples
 epParam("age"; "age=21") // Returns 21
epParam("age") // Returns the value of age contained in
Get(ScriptParameter)
epParam("age"; "age=21"; "exists") // Returns 1 because age exists in
paramsString
epParam("age"; "name=Joe"; "exists") // Returns 0 because age does not exist in
paramsString

Why Use epParam?

FileMaker 7 introduced the idea of using a single string to contain multiple Named Parameters. This allows
you to call a script with a script parameter string like

"name = \"Joe\"; age = \"21\""

and retrieve just the age parameter using the FileMaker expression:

Evaluate("Let([" & Get(ScriptParameter) & "]; age)")

This expression is not easy to remember and looks rather confusing. W orse, in some FileMaker versions it
will return "?" if your script parameter contains too many spaces, a semicolon in the wrong place, or two
copies of the age parameter. If your script parameter doesn't contain an age parameter but your FileMaker
database has a field called age, Evaluate(...) will actually return the value from your database field!
epParam corrects all these problems.

epParam is case sensitive. That means epParam("name"; "name=Joe") will return Joe, but
epParam("Name"; "name=Joe") will return blank because name is not capitalized in the
Named Parameter string.

epFMNameID
This function requires FileMaker 8 or later.

epFMNameID( nameOrID; type {; fileName }{; layoutName } )

epFMNameID takes the name or numeric ID of a FileMaker object and returns the opposite (given a name,
it returns an ID, given an ID, it returns a name). The FileMaker object may be a Table, Layout, Field, Script,
or Value List.
nameOrID is the name or ID of the FileMaker object.
type is the type of the FileMaker object and must be one of the following values:

"Table" or "T" : nameOrID represents a FileMaker Table.

"Layout" or "L" : nameOrID represents a FileMaker Layout.
"Field" or "F" : nameOrID represents a FileMaker Field.
"Script" or "S" : nameOrID represents a FileMaker Script.
"ValueList" or "V" : nameOrID represents a FileMaker Value List.
fileName is the name of the database containing nameOrID. Default is the current database.

layoutName is the name of the layout containing a nameOrID of type "Field" . Default is the current
layout.
Why Use epFMNameID?
One of the nice things about using FileMaker is that you can normally rename FileMaker objects such as
fields, tables, scripts, and layouts without breaking your database. For example, a script that calls
My Script will continue to call the correct script if you change the name of My Script to My Renamed Script .
Sometimes you'll want to pass the name of a FileMaker object like a script to a function such as
epScriptQueue which is part of the free 2empowerFM Script Scheduler plug-in. Unfortunately, when you
call epScriptQueue("My Script") , if you ever change the name of My Script , epScriptQueue will no longer
be able to find the script.
Y ou can prevent renamed scripts from breaking epScriptQueue by adding a call to epFMNameID as
follows:

epScriptQueue( epFMNameID(37; "S") ) // "My Script"

It is now safe to rename My Script and epFMNameID(37; "S") will return the new name. Adding
// "My Script" after the call to epFMNameID is a helpful reminder of what script is being called, but it isn't
necessary.

The script ID of 37 is just an example and every script will have a different ID. To get the ID of My Script ,
call epFMNameID like this:

epFMNameID("My Script"; "S")

Y ou can call the above from the Watch tab in Data Viewer or use the Evaluate button in 2empowerFM
Developer Assistant.
The ID of every FileMaker object (scripts, fields, tables, layouts, and value lists) will never change in a
particular database no matter how many times you rename the object or move it around in a list of object.
FileMaker object IDs will not change even when the database is duplicated or converted from FM7 to FM12
format. Each object has a different ID, and even if you delete the object, its ID will will never be used for
any other object you create. On the other hand, two objects of different types, such as a script and a field,
may share the same ID, which is why the second parameter of epFMNameID is necessary to indicate what
type of object the ID refers to.

If you get in the habit of using epFMNameID in a lot of places, consider appending the ID of
things like scripts to the name of the script so you don't have to keep looking it up. For
example, My Script in the example above could be renamed to My Script (37) .

epFMNameID is based on the FM_Name_ID function created by Fabrice Nordmann and is used with
permission. More information about FM_Name_ID can be found here. epFMNameID takes the same
parameters as FM_Name_ID but because epFMNameID is a plug-in function instead of a FileMaker
"Custom Function", the last two parameters could be made optional.

W hen dealing with fields, if your database will always run in FileMaker 10 or later, use
FileMaker's GetFieldName function to avoid replacing table and field names with IDs. For
example, we can check if the "active field" (the field the user has the cursor in) is equal to
MyTable::MyField:
If( Get(ActiveFieldTableName) & "::" & Get(ActiveFieldName) =
GetFieldName(MyTable::MyField); ... )
The epFMNameID equivalent would be:
If( Get(ActiveFieldTableName) = epFMNameID(123; "T") and Get(ActiveFieldName) =
epFMNameID("123::5"; "F"); ... )
Unfortunately, FileMaker has no function similar to GetFieldName for tables, layouts, scripts,
or value lists.
 epFMNameID can only identify fields that exist on whatever layoutName you pass as the
4th parameter. If you don't provide a layoutName, the name of the current layout is used.
That means if the current layout changes, calls to epFMNameID that used to work could
break. To more safely call epFMNameID to get a field name, pass in the name of a layout
you know will contain the field as the 4th parameter:
epFMNameID("6"; "F"; ""; epFMNameID("3"; "L") )
In the example above, 6 is the ID of the field and 3 is the ID of the layout containing the
field. This method will still break if you ever remove the field from the layout with ID 3 or if
you delete that layout, so use FileMaker 10's GetFieldName function whenever possible.
Fields are the only thing affected by the layoutName parameter, so using epFMNameID for
tables, layouts, scripts, or value lists should be safe.

Examples

epFMNameID("My Script"; "Script") // Returns numeric ID of "My Script"

epFMNameID(21; "Script") // Returns name of script ID 21
epFMNameID("MyField"; "Field") // Returns ID of MyField on the current layout.
epFMNameID("MyField"; "Field"; ""; // Returns ID of MyField visible in MyLayout in
"MyLayout") the current database.
epFMNameID("MyTable::MyField"; "Field"; // Returns ID of MyField in MyTable in MyDB,
"MyDB") regardless of layout.
epFMNameID("12345::32"; "Field") // Returns name of field ID 32 in table ID
12345.
epFMNameID("32"; "Field"; ""; epFMNameID(4; // Returns name of field ID 32 in layout ID 4
"Layout"))

epConfig
epConfig( "params" )

epConfig is used to change the configuration of all 2empowerFM plug-ins. Some of its options can also be
set with the Preferences dialog.
"params" is a string containing one or more of the following Named Parameters:
setErrorCapture: Like FileMaker's Set Error Capture script step, turning on 2empowerFM error
capture prevents dialog boxes from appearing when 2empowerFM encounters errors. May be one of the
following values:
On : epVar("$lastError") is cleared and will be set to the value of the last message that
would otherwise have been shown in an error dialog. Note that when a plug-in is run on
FileMaker Server or IW P/W ebDirect, any value given to setErrorCapture will be interpreted as
On .
Append : epVar("$lastError") is cleared and every message that would otherwise be shown in
an error dialog is appended to epVar("$lastError"). Each error message in
epVar("$lastError") is separated by a line break so that you can use FileMaker's
ValueCount() function to count the errors and MiddleValues() to look at each error.
Off : Stop capturing errors. The value of epVar("$lastError") is not changed.
getErrorCapture: Causes epConfig to return On , Append , or Off depending how 2empowerFM error
capture is currently set. W hen running on FileMaker Server or IW P/W ebDirect, On is the only value
that will ever be retuned.
showT oolboxOnStartup: Controls whether the 2empowerFM T oolbox will be shown next time
FileMaker is started and the first database is opened. This preference is saved on each computer. May
be one of the following values:
Y es : 2empowerFM Toolbox is shown. (default for FileMaker Pro Advanced and Developer)
No : 2empowerFM Toolbox is not shown. (default for FileMaker Pro)
 showT oolbox: Shows or hides the 2empowerFM T oolbox immediately. May be one of the following
values:
Y es : Show the 2empowerFM Toolbox.
No : Hide the 2empowerFM Toolbox.
getT oolboxShowHotkeyDesc: Return a description of the hotkey assigned to show the
2empowerFM T oolbox.
getT oolboxHideHotkeyDesc: Return a description of the hotkey assigned to hide the 2empowerFM
T oolbox.

Examples

epConfig("setErrorCapture=On")
epConfig("getErrorCapture") // Returns "On"
epConfig("showToolboxOnStartup=No checkForUpdates=No")

epLicense
epLicense( { "optionalParam" }; { licenseVersion; firstName; lastName; organization; maxUsers;
key; purchaseDate; licenseDescription; unlockedPlugins } )

Set the person and organization that 2empowerFM is licensed to and what plug-ins they're licensed to use.
W hen you purchase, you should receive instructions containing the exact parameters you need to supply to
install your license.

W hen your license is successfully installed, epLicense returns an empty string ( "" ). On failure, an error
dialog will pop up explaining what went wrong and epLicense returns ? .
"optionalParam" may contain any one of the following Named Parameters:
getLicensesInstalled: Return your license information in a format that can be interpreted using
epParam or Evaluate("Let(["...) . It will return ? if no licenses are installed or if 2empowerFM is not
installed.
makeT emporary: Make the installation of a non-developer license temporary. The license will not be
saved to disk and will disappear when FileMaker is shut down.

This option should be used if you need to temporarily use a license on a computer you
do not own. W e recommend embedding a call to epLicense("makeT emporary"; ...)
within a database that is password-locked against editing. The database can contain
an Install License button that asks for a password before it will run the embedded
epLicense() function. By using a password-locked database, your license can't be
stolen by passing it to the foreign computer using a plain text file or unlocked
database.

removeAllRegularLicenses: Uninstall all regular (non-developer) licenses. The only time you might
need to do this is if you want to replace a license that is too old to work with a new version of
2empowerFM with a new license.
removeLicense: Uninstall a single license. Must be followed by all the parameters of the installed
license, including licenseVersion, firstName, etc.
For more information on how and when to call epLicense, see the Install License section.

epVar
epVar( { name }{; value } )

epVar gets or sets a FileMaker or 2empowerFM variable.

Set a Variable's Value

To set a variable called myVar to myValue , call:

epVar("myVar"; "myValue")

Get a Variable's Value

If no value is provided, the variable is returned instead of set:

epVar("myVar") // Returns "myValue". This is the value we just assigned to "myVar" in the
previous example.

Requesting a variable name that has never been set will not return an error, it will return an empty string
( "" ).

Variable Scope
The first character in a variable's name is used to determine what scope the variable has.
A variable like myVar that does not begin with any special character is created with script scope.
A script scope variable is only accessible from the script you create it in, so myVar in Script A
will have a different value than myVar in Script B.
In FileMaker 8 and later, epVar("myVar"; "myValue") will set a FileMaker variable called $myVar
to "myValue".
In FileMaker 7, which does not support variables, myVar will be stored internally to the plug-in.

Because FileMaker does not inform plug-ins when a script has finished executing,
script scope variables are not automatically erased in FileMaker 7. To avoid
reading values from a previous execution of a script, call
epVar("$eraseScriptVars") at the start of each script where you use script
scope variables. This is only necessary in FileMaker 7 and will have no effect in
later versions.

@ begins a database scope variable which means @myVar will refer to a different value for each
database it's used in.
In FileMaker 8 and later, epVar("@myVar"; "myValue") will set a FileMaker variable called
$$myVar to "myValue".
In FileMaker 7, which does not support variables, @myVar will be stored internally to the plug-
in.
Try to choose longer names for database scope variables to limit the possibility of overwriting
another database scope variable you forgot you used elsewhere.
* begins a global scope variable which means *myVar will refer to the same value no matter where
you access it from, in any database.
Note that FileMaker often refers to its double-dollar-sign $$variables as "global", but they
actually have database scope because $$myVar will have a different value in each database.
Since *myVar is truly global in scope, you can use it for things like storing temporary user
preferences or filters that affect database relationships in multiple databases.
It's usually best to use database scope variables instead of global scope variables to avoid
overwriting global scope variables created in databases you didn't design.
# begins window scope variable which means #myVar will refer to a different value for every open
database layout window.
$ begins a 2empowerFM system variable, such as $lastError .
A system variable is created by 2empowerFM for various special purposes, such as to hold the
last captured error message.
Y ou should not set a system variable yourself because it could be overwritten or erased by the
system, but epVar will not prevent you from setting a system variable if you feel you have to.
System variables have global scope.
 Variables of all scopes are specific to a particular copy of FileMaker, even when using a
database hosted by FileMaker Server or hosted by another copy of FileMaker. For example,
setting a database scope variable in one copy of FileMaker will never affect a database
scope variable of the same name on any other copy of FileMaker.

Erase All Variables In Scope

Except for calling epVar("$eraseScriptVars") at the start of a script in FileMaker 7, there should rarely be a
reason erase all variables in a particular scope. However, if you find you need to erase a scope of variables,
you may issue one of the following system commands. Like system variables, all commands begin with $:

epVar("$eraseScriptVars")
This command does nothing in FileMaker 8 and later because it is not possible for a plug-in to
list or erase FileMaker's $variables.
epVar("$eraseDatabaseVars")
This command does nothing in FileMaker 8 and later because it is not possible for a plug-in to
list or erase FileMaker's $$variables.
epVar("$eraseGlobalVars")
epVar("$eraseW indowVars")
epVar("$eraseSystemVars")

See All Variables

To see the values of all variables stored internally in 2empowerFM, click the epVars button on the
2empowerFM T oolbox's Utility T ab. This list does not include values of script scope and database scope
variables stored by FileMaker in FileMaker 8 and later. Later FileMaker Pro Advanced versions will show you
script scope and database scope variables in the Current tab of the Data Viewer (available by clicking
FileMaker's T ools > Data Viewer menu).

Examples

epVar("myNum"; 4) // Sets a script scope variable named "myNum" to the value 4. In

FileMaker 8 and later, this sets FileMaker variable $myNum to 4.
epVar("myNum") // Returns 4 (the value of "myNum" or $myNum in FileMaker 8 or later)
epVar("@myNum"; 4) // Sets a database scope variable named "myNum" to the value 4. In
FileMaker 8 and later, this sets FileMaker variable $$myNum to 4.
epVar("#myNum"; 4) // Sets a window scope variable named "myNum" to the value 4.
epVar("*myNum"; 4) // Sets a global scope variable named "myNum" to the value 4.
epVar("$lastError") // Returns the system variable named "lastError".

epVersion
epVersion( { "parameters" } )

If you look in the FileMaker Extensions directory where Developer Assistant is installed, you will find two
plug-in files: 2empowerFM and 2empowerFM_Developer_Assistant. That's because every plug-in in the
2empowerFM family uses a shared plug-in called 2empowerFM which usually appears as 2empowerFM
Parent in dialogs that list plug-ins. The epVersion function can return the version number of either of
these two plug-in files by specifying the name of the plug-in file using the plugin Named Parameter in
"parameters".

W hen a plug-in file is not installed, epVersion returns ? . FileMaker also returns ? when the epVersion
function is not found (meaning the 2empowerFM plug-in file is not installed).
To make sure a plug-in file is installed and is the version number you require, check that this is true:
 epVersion("plugin=2empowerFM_Developer_Assistant") >= "03450000"

There is no need to check the version number of epVersion("plugin=2empowerFM") because

epVersion("plugin=2empowerFM_Developer_Assistant") will return ? when the 2empowerFM plug-in file is
not installed or is an incompatible version.
"parameters" may contain any of the following Named Parameters:
plugin: File name (without .fmx64 or .fmplugin extension) of the plug-in to return the version number
of.
Possible values:
2empowerFM (default)
2empowerFM_Clipboard_Explorer
2empowerFM_Developer_Assistant
2empowerFM_Dialog_Master
2empowerFM_Hands-Free_Printer
2empowerFM_Keyboard_and_Mouse
2empowerFM_Layout_Painter
2empowerFM_Menu_Popper
2empowerFM_Money_and_Numbers
2empowerFM_Script_Scheduler
2empowerFM_SQL_Runner
2empowerFM_Text_Toolkit
2empowerFM_Tweak_UI
format: Set to one of the following values:
AutoUpdate: Return the version number as an 8-digit string (default).
Example: Version 1.234 is returned as 01234000 .
This 8-digit string format was devised by a group of plug-in developers as a standard
method for returning version numbers that can be reliably compared to previous and future
version numbers. For example, if 2.1 was returned as a string, in some regions the
decimal point is not represented by a dot but by a comma and this string would not be
interpreted as a number. Therefore, version 2.1 would not necessarily be considered
greater than version 2.0 in some regions. Version 02100000 is always considered greater
than version 02000000 in all regions.
ForDisplay: Return a version number string that can be used to display the version number in a
more human-readable way.
Example: Version 1.234 is returned as 1.234 .
This format returns a string instead of a number because the number 2.0 would be
displayed as 2 instead of 2.0 . By returning 2.0 as a string, the .0 part is not lost.
Another problem with returning numbers is that if a number such as 2.1 were returned, it
would be displayed as 2,1 (2 comma 1) instead of 2.1 (2 dot 1) in some regions of the
world.
Path: Return path to the plug-in file.
Example: C:\Users\John\AppData\Local\FileMaker\Extensions\2empowerFM.fmx64 on
W indows or
/Users/John/Library/Application Support/FileMaker/Extensions/2empowerFM.fmplugin on
OS X.
The path isn't technically version information but many plug-in authors have added a path
result option to their version function so we did the same.

Examples
epVersion("plugin=2empowerFM") // Returns the version of the "2empowerFM" plug-in in
"AutoUpdate" format.
epVersion("plugin=2empowerFM // Returns the version of the "2empowerFM" plug-in in
format=ForDisplay") "ForDisplay" format.
epVersion("plugin = // Returns the version of the "2empowerFM_Tweak_UI"
2empowerFM_Tweak_UI") plug-in in "AutoUpdate" format.
epVersion // Returns the version of the "2empowerFM" plug-in in
"ForDisplay" format. Although "ForDisplay" is not
normally the default format, it was the format that
epVersion used to return when it did not accept
additional parameters.
About Dialog, Install License, and Preferences
The About 2empowerFM Dialog
The About 2empowerFM Dialog contains information about all 2empowerFM plug-ins you have installed.
This includes plug-in version, remaining time in any 30-day trial periods you have started, and information
about what licenses you have installed.
To open the About 2empowerFM Dialog, first open FileMaker's Plug-In Preferences as follows:
Click FileMaker's Edit menu on W indows, or the FileMaker Pro menu on Mac, then choose Preferences...

Click the Plug-Ins tab, choose 2empowerFM Parent v2.71, then click Configure...

Y ou will be shown the About 2empowerFM Dialog which contains information about any licenses you have
purchased as well as time remaining in trial periods for any 2empowerFM plug-ins you have installed:
At this point, you can click Install License which is discussed in the next section, or Preferences which is
discussed in the Preferences section that comes after Install License.

Install License
If you want to install a Developer License (also known as a Redistribution License) purchased from
www.2empowerFM.com, please skip down to the Installing a Developer License section. To install a
standard User license, or.if you aren't sure which type of license you have, click the Install License button
in the About 2empowerFM Dialog pictured above. The following window will appear:

Copy the epLicense function you received when you purchased the plug-in. Copy all text starting from
epLicense( and ending with ) , then click the Paste License button. The License 2empowerFM window
should now look something like this:
Click Install License. If you tried to install a Developer license, an error will be shown and you should follow
the instructions in the next section. Otherwise, a dialog will tell you the license was installed, and when
you click Close, the license should apear in the About 2empowerFM Dialog.
Licenses can also be installed by calling the epLicense function from any FileMaker calculation such as the
Set Variable step of a script. Once installed, a User license is saved on the machine it was installed on and
will remain installed until you uninstall it. Uninstalling a User license is not usually necessary, but it can be
done using additional parameters available when calling the epLicense function.

Installing a Developer License

Unlike a User license, a Developer license (also known as a Redistribution license), is not saved on the
machine and is forgotten when FileMaker is closed. The Developer license is meant to be included in a
password-protected database or a FileMaker Runtime solution that you sell or distribute to other companies.
Since a developer license is not saved, it must be installed using a call to epLicense in a startup script. The
license is also linked to the particular database the epLicense function was called in and it will not work in
other running databases. If you need to license more than one database at a time, you must call
epLicense in each database.

Developer License with FileMaker Runtime

A FileMaker Runtime Solution is the best way to distribute your FileMaker application with 2empowerFM
plug-ins. To distribute plug-ins with your runtime, the parent 2empowerFM and child plug-in (such as
2empowerFM_SQL_Runner) must be copied to the Extensions folder within your Runtime's folder:

If you've been using 2empowerFM plug-ins from your Runtime without copying them to the Extensions folder
pictured above, it's because you installed the plug-ins to the shared folder used by all copies of FileMaker,
including Runtimes. However, the plug-ins will not be available when you distribute the Runtime to another
computer unless you copy the plug-ins to the folder pictured above.
To install a license in a Runtime solution, create a script called Startup Script (the actual name doesn't
matter) with the following step. Y ou can also add this step to an existing startup script if you already use
one:

Set Variable [$result; Value: epLicense(2; "First Name"; "Last Name"; "Company Name"; "1";
"ABCDEFGHIJKLMNOPQRSTUVW XY Z"; "01-02-2015"; "Licensed to use all functions in products
sold by Dracoventions"; "ABCDEFGHIJKLMNOPQRSTUVW XY Z")]

Replace the epLicense call above with your actual license.

Open the File > File Options... menu:

In the Open/Close tab, click Specify... next to Peform script: then choose your Startup Script and click
OK:

Developer License with Password-Protected FileMaker

Installing a license in a password-protected FileMaker database takes a number of additional steps
compared to using a Runtime solution. First, you must ensure that anyone using the FileMaker database
also installs the 2empowerFM plug-ins your database uses. Starting in FileMaker 12, you can include a plug-
in in a Container field and install it by calling the Install Plug-In File script step:

W hen installing 2empowerFM plug-ins using the Install Plug-In File script step, you must
install all child plug-ins first (ie 2empowerFM_SQL_Runner.fmplugin) followed by the
parent plug-in (2empowerFM.fmplugin).

To license your plug-ins after they are installed, follow the steps in the Developer License with FileMaker
Runtime section above to set up a Startup Script that calls epLicense. After that, you must add a
password so that nobody else can look at that Startup Script and see your license. Add that password by
opening the File > Manage > Security... menu. Look at the Privlege Sets tab:

The above is the default set of privileges for a new database. Only the [Full Access] privilege set has
access to look at scripts, and only the Admin account has been assigned to the [Full Access] privilege set.
As long as you assign a password to the Admin account that you do not share with anyone you give your
database to, those users will not be able to look at scripts and steal your 2empowerFM plug-in license.
To assign a password to the Admin account, switch to the Accounts tab, click the Admin account line, click
Edit..., then type a password in the Password: field:

Activate the Guest account by clicking the checkbox on its line, and make sure it says [Read-Only Access]
as its Privilege Set:

To keep users of your passsword-protected database from being prompted to enter a password when they
open the database, you can set the database to automatically log in the Guest user. Open the File > File
Options... menu again, choose the Open/Close tab, check Log in using: and Guest Account:
Now, when you open your database, you will not be prompted for who to log in as. To be able to edit your
database, you will need to log in as the Admin user again. Y ou can do that by holding Option or Alt
while you open the database, or you can add a button to one of your layouts that calls Re-Login either as a
script step or as an action triggered directly by clicking the button:

If you need users of your database to be able to look at some scripts, but not the Startup Script containing
your license, you can create a privilege set with Scripts: set to Custom privileges... and set Startup Script
to no access:

Assign your custom privilege set to the Guest account or to whatever accounts you want to allow access to
selected scripts.

Uninstall License
After you install at least one license, the Uninstall Liense button will appear in the About 2empowerFM
Dialog:
Click Uninstall License and the following window will appear:

Pick which license you want to uninstall using the pulldown to the right of Uninstall which license?, then
click the Uninstall button.
If you need a way to uninstall licenses from a script or other FileMaker calculation, please see the
epLicense function.

Preferences
Click the Preferences button in the About 2empowerFM Dialog to open the 2empowerFM Preferences
window:

Report weekly usage statistics to Dracoventions.com

W hen you check this option, information about usage of any 2empowerFM plug-in is sent to
Dracoventions.com each week to help us see what parts of each plug-in are popular and should be
improved. The report includes your OS and FM versions, counts of 2empowerFM functions called, and a
 hashed string that uniquely identifies you but provides no actual information about you or your
computer. No personal information is sent back to Dracoventions. Default is unchecked.
Open T oolbox on FileMaker startup
W hen you check this option, the 2empowerFM T oolbox is displayed whenever FileMaker starts. Default
is unchecked in FileMaker Pro and checked in FileMaker Pro Advanced.
When T oolbox is closed, show how to open it again
W hen you check this option, a dialog explaining how to open the 2empowerFM T oolbox again is
displayed the first time the Toolbox is closed. This explanation dialog is only showed if the
2empowerFM T oolbox was opened at FileMaker startup. Default is checked.
Hotkey to show T oolbox
The hotkey set here will show the 2empowerFM T oolbox if it is hidden. By default, the Toolbox is
shown by holding Command , Option , and Shift , then pressing X on Mac, or by holding Ctrl , Alt ,
and Shift , then pressing X on W indows. Both of these key combinations are represented by the Key-
Combo String CAS-X.
Hotkey to hide T oolbox
The hotkey set here will hide the 2empowerFM T oolbox if it is currently shown. By default, the
Toolbox is hidden by holding Command , Option , and Shift , then pressing X on Mac, or by
holding Ctrl , Alt , and Shift , then pressing X on W indows. Both of these key combinations are
represented by the Key-Combo String CAS-X.
Show All Errors
Certain types of error message will include a checkbox that says Stop showing me this kind of error. If
you later want to see that type of error again, the only way to do so is to show all types of errors by
clicking the Show All Errors button.

Key-Combo Strings
A Key-Combo String is a short string such as

S-X

that represents a combination of keys on your keyboard. In this case, S means hold Shift , while X means
to press the X key.
The Key-Combo String is written in the following format:

modifier-key

modifier- is optional and specifies additional keys that must be held down before key is pressed.
modifier- may be one or more of the following characters, followed by a dash:
C means Ctrl on W indows or Command on Macintosh.
A means Alt on W indows or Option on Macintosh, although it is often labeled as Alt even on a
Macintosh keyboard.
S means Shift on W indows or Shift on Macintosh.
W means W indows key on W indows or Ctrl ^ on Macintosh.

key may be any single-character key on the keyboard (such as X), or one of the following key names:
ENT ER, ESCAPE, T AB, BACKSPACE, DELET E, HOME, END, LEFT , RIGHT , UP, DOWN,
PRINT SCREEN, F1 through F12
CONT INUE is used in special circumstances to press the appropriate keys to continue a paused script
or perform a find.
Examples:

AS-X

means hold or Option and Shift on Macintosh or Alt and Shift on W indows, then press the X key. The
order of the modifier letters does not matter. the same hotkey could also be written as SA-X

simply means to press the Y key.