360Works ScriptMaster User Guide

Introduction

ScriptMaster is a free, general-purpose, modular plugin. It includes modules for file manipulation, URL and network utilities, Web Services, shell scripting, event/script triggering, and many others. Modules for ScriptMaster are written in a programming language called Groovy, which is very similar to Java. Because they are so similar, we often use the terms Java and Groovy interchangeably in this documentation, although it is more technically accurate to refer to it as Groovy. You do not need to be a Java programmer to use ScriptMaster, but if you are, you can write your own modules or enhance the ones that come with it.

ScriptMaster modules work just a lot like FileMaker custom functions: They take some named input parameters, process those inputs, and return an output. They appear in your FileMaker function list, just like custom functions.

In other ways, however, they improve on what you can do with custom functions. Custom functions only allow you to do things you can already do with features built into FileMaker, but ScriptMaster modules can access all of the power in the Java language and class libraries. It's also easier to share ScriptMaster modules across all of your FileMaker files than sharing custom functions, because custom functions must be duplicated into every FileMaker file, while ScriptMaster modules are available to every file running in FileMaker.

To get started with ScriptMaster, start by installing the ScriptMaster plugin (see installation instructions below). Then open the ScriptMaster.fp7 file that comes with it. You'll see a list of all of the modules that come with ScriptMaster. To try one out, click on it in the list view. 'Screen Capture' is a good one to start with, because the Java code is very short and easy to understand, and it also demonstrates how to work with data in container fields. Click the 'Evaluate Script' button to run the module, which will execute the Java code based on the values set for the input variables. The 'Evaluate Script' button is a very easy way to try out modules in the development file, but it's not how you would use it within your own solution. For that, we'll talk about registering this as a function.

Registering functions

Registering a function will make it appear in your list of available FileMaker functions. Because it compiles the code, it will also run much faster as a registered function than using the 'Evaluate Script' button. To register a module, simply click the register button. This takes you to the registration screen, compiles the code, and adds it to the list of available FileMaker functions. You can see this by going into the calculation dialog and pulling down to the 'External functions' grouping. The registered function will appear under the 'ScriptMaster' section, and can be called just like any other built-in FileMaker function.

Now that you've registered the function, you're almost ready to start using it in your solution. The only problem is that functions only remain registered while FileMaker is running - if you were to quit FileMaker and start it back up, the module you just registered would no longer appear in the FileMaker functions list. We'll discuss two options for registering ScriptMaster modules every time you open your solution file.

The first option, which is the one that we recommend in most cases, is to simply check the 'register on startup' box from the registration screen (the layout that you are taken to after clicking the 'register' button). All modules with this option enabled are registered every time you open the ScriptMaster.fp7 file, so you can just include the ScriptMaster.fp7 file with your solution, open it in your startup script, and then immediately close it (it doesn't need to stay open after the functions have been registered). Here's an example of what you would put in your startup script:

Open File ["ScriptMaster"]
Close File ["ScriptMaster"]

We recommend this option because it is very easy to use. Plus, if you uncheck the 'Ask user before installing plugin' checkbox, you can have the ScriptMaster file install the ScriptMaster plugin for you. Please refer to the '1-2-3 Go' section of the demo file for more information.

The second, more advanced option is to copy the registration code into your own startup script. This is a better choice if you do not want to include the ScriptMaster.fp7 file with your solution. To do this, click the 'copy' button from the registration screen. This puts all of the registration code onto your clipboard. Now go to the startup script in your solution, add a 'set variable' script step (you can name the variable anything you like), and paste in the registration code as the formula to calculate. Now the function will be registered every time that your startup script runs. Here's what that script step would look like:

Set Variable [$result; Value:RegisterGroovy( "GetURLasText( url )"; "new URL(url).getText();" )]

It is a good idea to check for errors after registering the function, in case there is any problem compiling the Java code. See the section below on error reporting, or watch the Youtube movie in this documentation to see an example of this complete setup. Here is an example that does the same thing as the previous one, but checks for errors and displays them to the user in case the function cannot be compiled:

If [RegisterGroovy( "GetURLasText( url )"; "new URL(url).getText();" ) = "ERROR"]
Show Custom Dialog ["Could not register ScriptMaster function"; SMLastError]
End If

Pricing

The ScriptMaster plugin is completely free. You may distribute it with your own solution. It would be great if you mention 360Works or ScriptMaster in your documentation / about screen, but there is no requirement that you do this. This plugin may be deployed with the Web Publishing Engine, for scripts that will be called from Instant Web Publishing or Custom Web Publishing. It may also be deployed on FileMaker Server for use with scripts that are scheduled to run on the server. See the installation section below for more information on how to do this.

Tutorial video

We've created a video showing how to use ScriptMaster. This is a quick (9 minute) jump-start showing you how to register a module and incorporate it into your solution.

Advanced techniques

Your ScriptMaster functions can reference compiled Java libraries (stored in a the .jar format) by using the SMLoadJar function. Pass in a container field containing a .jar file, or a URL pointing to a .jar file, and any scripts you execute will have access to the classes in that .jar. This means you can access libraries like iText (a powerful PDF manipulation library) or qtjava (QuickTime for Java) from within FileMaker. You could also easily write your own java code, package it as a .jar, and distribute it with your FileMaker solution! And since the .jar is stored in FileMaker, deploying new versions of the java code to the FileMaker clients is as easy as updating a single container field.

Keep in mind that if you are copying and pasting the function registration into your startup script, and that module requires any jar libraries, you will need to add those jar files to container fields in your solution and use SMLoadJar to load them before registering the function. This is not an issue if using the 'register on startup' option with the ScriptMaster.fp7 development file, since that file includes all of the jar files needed for the modules that come with ScriptMaster.

After a ScriptMaster function executes, you can access any of the named variables which were set during execution using the SMGetVariable function. This can be very useful for returning multiple output values, similar to setting global variables in a FileMaker script.

Getting help

If you get the word 'ERROR' as the result of a ScriptMaster function, be sure to read the section below on Error reporting for how to get more information on that.

Phone and e-mail support for ScriptMaster are available at our standard hourly rate of $155. There is also a free ScriptMaster discussion forum where you can get help from the growing community of ScriptMaster users.

If you create your own module that you think would be useful to others, post it on the fmforums discussion group! If it seems like it will have broad appeal, we'll include it with the next release of ScriptMaster (preference will be given to modules that do not require 3rd party libraries).

New modules

In addition to the many existing modules that come free with ScriptMaster, 360Works is available to create custom modules suited to your specific needs. Send us an email ( plugins@360works.com ) or give us a call at 866-662-9185 and let us know what you're looking for, and we'll get you an estimate at no charge.

The other choice is to do it yourself! We want to start off by stressing that you can skip the rest of this section if you're not interested in learning Groovy or Java. ScriptMaster comes with tons of useful modules that you can use without having to learn a new programming language. However, if the built in modules have stirred your curiosity, you'll be able to take your FileMaker solutions to a whole new level with the power of Groovy and Java. Because Groovy is cross-platform, modules you create will run on both Windows and Mac OS X.

To create your own module, just create a new record from the menu. Give it a title and start coding! You can learn about Groovy at http://groovy.codehaus.org/Beginners+Tutorial (you can skip all of the steps about setting up your Java and Groovy environment; that's all taken care of by ScriptMaster).

Here are a few tips about using ScriptMaster with FileMaker:

In the 'Screen Capture' module, one thing you'll notice is that the Integer.valueOf() calls at the beginning. This is because all ScriptMaster functions are transmitted as text. The Integer.valueOf(someText) translates this into a numeric value. Java is much stricter about data types than FileMaker, so this can take some getting used to for FileMaker programmers.

In addition to setting variables prior to script execution, you can access the FileMaker calculation engine directly from within your Groovy script. This is accomplished using the reserved fmpro object. Every Groovy script which is executed will have an fmpro variable set to an instance of an FMPro object, which has these important methods:

evaluate(fmcalculation)

Evaluates the supplied FileMaker calculation text, returning the result as a String. The fmcalculation parameter can be any valid FileMaker calculation string.

performScript(fileName, scriptName [ , paramString ])

Performs a FileMaker script in the current file, passing in the optional paramString as a parameter. Note: fileName is required.

merge(template)

Processes some text with merge fields embedded, replacing the merge fields with their evaluated values. An example of a merge field is <<table::field>>. If an error occurs during evaluation, the field is left as is.

A script evaluated in ScriptMaster always returns the value of the last line, or the value which is implicitly returned by the script. This can be any type of Java object. ScriptMaster does its best to convert this to a FileMaker object.

The following conversions occur:

• Strings and Readers are returned as Filemaker TEXT fields, with newline characters (\n) converted to carriage returns (\r). If you are returning a very large block of text, you should return a Reader.
• Numbers and numeric primitives are returned as FileMaker NUMBER fields
• Boolean values are returned as a 0 or 1
• File objects are converted to embedded containers
• Arrays and Collections are converted to return-separated lists
• URLs are converted to embedded containers
• Colors are converted to a string like RGB(204,102,255)
• RenderedImage, BufferedImage are converted to container images. If the image has transparency, it is converted to a PNG image. Otherwise it is converted to a JPEG.
• FMType objects are returned as-is.
• Any other object is converted to a String and returned as Text.

Set Variable [ $result = MyPluginFunction("x" ; "y" ; "z") ]
If [ $result = "ERROR" ]
    Show Custom Dialog [ "An error occurred: " & SMLastError ]
End If

// chain multiple calls together
// if any of the functions fail, the calculation will 
// short-circuit with a result of false,
// and none of the subsequent function calls will be evaluated.
Set Variable [ $success = 
    FirstPluginFunction("x") and 
    SecondPluginFunction("y") and 
    ThirdPluginFunction("z") 
]
If [not $success]
    Show Custom Dialog [ "An error occurred: " & SMLastError ]
End If

Set Variable[$result = RegisterGroovy (
    "logMessage ( text )" ;
    "System.out.println(text)"
)