Difference between revisions of "360Works ScriptMaster/Documentation"

From 360Works Product Documentation Wiki
Jump to navigation Jump to search
m (fixed fmforums link)
(Tags/code is broken (open tags, etc.) - fixing)
 
(5 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
=360Works ScriptMaster User Guide=
 
=360Works ScriptMaster User Guide=
−
<h3>Introduction</h3>
+
<h3>Introduction</h3>  
−
ScriptMaster is a free, general-purpose, modular plugin. It includes modules for file manipulation (reading, writing, copying, deleting,
 
−
zipping/unzipping, and moving files on the hard drive); downloading URLs and submitting forms online; XML Web Services; shell scripting;
 
−
and many others including screen capture, encryption, SQL access and clipboard access. 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. <b>You do not need to be a Java programmer to use
 
−
ScriptMaster</b>, but if you are, you can write your own modules or enhance the ones that come with it.</p>
 
  
−
ScriptMaster modules work just like FileMaker custom functions: You pass in some inputs and get back an output. They appear in your FileMaker
+
<p>ScriptMaster is a free, general-purpose, modular plugin. It includes modules for file
−
function list, just like custom functions.</p>
+
manipulation (reading, writing, copying, deleting, zipping/unzipping, and moving files on the hard drive);
 +
downloading URLs and submitting forms online; XML Web Services; shell scripting; and many others including screen
 +
capture, encryption, SQL access and clipboard access. 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. <b>You do
 +
not need to be a Java programmer to use ScriptMaster</b>, but if you are, you can write your own modules or enhance
 +
the ones that come with it.</p>  
  
−
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  
+
<p> ScriptMaster modules work just like FileMaker custom functions: You pass in
−
with features built into FileMaker, but ScriptMaster modules can access all of the power in the Java language and class libraries. It's also  
+
some inputs and get back an output. They appear in your FileMaker function list, just like custom functions.</p>
−
easier to share ScriptMaster modules across all of your FileMaker files than sharing custom functions, because custom functions must be duplicated  
+
In other ways, however, they improve on what you can do with custom functions. Custom functions only allow you to
−
into every FileMaker file, while ScriptMaster modules are available to every file running in FileMaker.</p>
+
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.</p>  
  
−
To get started with ScriptMaster, install the ScriptMaster plugin by copying it into your FileMaker extensions directory (complete installation  
+
<p>To get started with ScriptMaster, install the ScriptMaster plugin by copying it into your FileMaker extensions directory (complete installation
−
instructions can be found below). Then open the ScriptMaster.fp7 file that comes with it. At the top, click on 'ScriptMaster Modules' which  
+
instructions can be found below). Then open the ScriptMaster.fp7 file that comes with it. At the top, click on
−
will show you a list of all of the modules that come with ScriptMaster listed in order by Category. To try one out, click on it in the list view.  
+
'ScriptMaster Modules' which will show you a list of all of the modules that come with ScriptMaster listed in order
−
'Screen Capture' under the 'Containers' Category is a good one to start with.  This module will take a picture of some section of your screen  
+
by Category. To try one out, click on it in the list view. 'Screen Capture' under the 'Containers' Category is a good
−
and store it into a container field in FileMaker. You supply parameters for left, top, width, and height, which tells the module which section  
+
one to start with.  This module will take a picture of some section of your screen and store it into a container
−
of your screen to capture.  This is a good module to start with because the Java code is very short and easy to understand, and it also  
+
field in FileMaker. You supply parameters for left, top, width, and height, which tells the module which section of
−
demonstrates how to work with data in container fields. Click the 'Run Script' button with the green arrow to run the module, which will run  
+
your screen to capture.  This is a good module to start with because the Java code is very short and easy to
−
the module based on the values set for the input variables. After you run this, you should see a screen shot in the result area at the bottom  
+
understand, and it also demonstrates how to work with data in container fields. Click the 'Run Script' button with
−
of the screen (click on 'Enlarge' to see the full screen shot). Experiment with changing the inputs (left, top, width, and height) to see the  
+
the green arrow to run the module, which will run the module based on the values set for the input variables. After
−
result, and try out some of the other modules that come with ScriptMaster.</p>
+
you run this, you should see a screen shot in the result area at the bottom of the screen (click on 'Enlarge' to see
 +
the full screen shot). Experiment with changing the inputs (left, top, width, and height) to see the result, and try
 +
out some of the other modules that come with ScriptMaster.</p>  
  
−
<h3>Registering Modules As Functions</h3>
+
<h3>Registering Modules As Functions</h3>  
−
 
 
−
The 'Run 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
 
−
FileMaker solution. For that, we'll talk about registering this module as a function, which makes the module appear in your list of available
 
−
FileMaker functions. Because it <i>compiles</i> the code, it will also run much faster as a registered function than by using the 'Run Script' button.
 
−
To register a module, simply click the 'Register Function' button at the bottom of any module's screen. This compiles the code for the module,
 
−
adds it to the list of available FileMaker functions, and takes you to a screen showing that the module has been registered successfully.
 
−
You can see your registered ScriptMaster functions anywhere you'd get a calculation dialog in FileMaker (such as a calculation field or a
 
−
'set variable' script step) by 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.</p>
 
−
 
 
−
<img src="doc_images/ExternalFunctions.png" /></p>
 
−
 
 
−
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 three options for registering ScriptMaster modules every time you open your solution file.</p>
 
−
 
 
−
The first option requires ScriptMaster Advanced Edition. This is available for purchase for $95 per developer per year from
 
−
<a target="360site" href="http://www.360works.com/scriptmaster">http://www.360works.com/scriptmaster</a>, and is included in the
 
−
<a target="360site" href="http://www.360works.com/portfolio">360Works Portfolio License Bundle</a>. See the <a href="#licensing">licensing section</a> for more details.
 
−
With the Advanced Edition, click the 'plugin generation' button from the registration screen or the top of any other screen. This will
 
−
create a new plugin that you can name whatever you want and distribute to your customers along with your FileMaker solutions royalty-free.
 
−
This plugin is completely self-contained, and does not require either the ScriptMaster plugin or the ScriptMaster.fp7 FileMaker file.</p>
 
−
 
 
−
<img src="doc_images/GeneratedPlugin.png" /></p>
 
−
 
 
−
The second option 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:
 
  
 +
<p>The 'Run 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 FileMaker solution. For that, we'll talk about registering this module as a function, which
 +
makes the module appear in your list of available FileMaker functions. Because it <i>compiles</i> the code, it will
 +
also run much faster as a registered function than by using the 'Run Script' button. To register a module, simply
 +
click the 'Register Function' button at the bottom of any module's screen. This compiles the code for the module,
 +
adds it to the list of available FileMaker functions, and takes you to a screen showing that the module has been
 +
registered successfully. You can see your registered ScriptMaster functions anywhere you'd get a calculation dialog
 +
in FileMaker (such as a calculation field or a 'set variable' script step) by pulling down to the 'External
 +
functions' grouping. </p>
 +
<p>The registered function will appear under the 'ScriptMaster' section, and can be called just
 +
like any other built-in FileMaker function.</p> 
 +
<p><img src="doc_images/ExternalFunctions.png" /></p>  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 three options for
 +
registering ScriptMaster modules every time you open your solution file.</p>  The first option requires
 +
ScriptMaster Advanced Edition. This is available for purchase for $95 per developer per year from <a target="360site"
 +
href="http://www.360works.com/scriptmaster">http://www.360works.com/scriptmaster</a>, and is included in the <a
 +
target="360site" href="http://www.360works.com/portfolio">360Works Portfolio License Bundle</a>. See the <a
 +
href="#licensing">licensing section</a> for more details. With the Advanced Edition, click the 'plugin generation'
 +
button from the registration screen or the top of any other screen. This will create a new plugin that you can name
 +
whatever you want and distribute to your customers along with your FileMaker solutions royalty-free. This plugin is
 +
completely self-contained, and does not require either the ScriptMaster plugin or the ScriptMaster.fp7 FileMaker
 +
file.</p>  <img src="doc_images/GeneratedPlugin.png" /></p>  The second option 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"]
 
  Open File ["ScriptMaster"]
 
  Close File ["ScriptMaster"]
 
  Close File ["ScriptMaster"]
  
−
</p>
+
</p> The third option is the most complex, but it does not require ScriptMaster Advanced Edition, and it does
−
 
+
not require you to include the ScriptMaster.fp7 file with your solution. In the module registration screen, click the
−
The third option is the most complex, but it does not require ScriptMaster Advanced Edition, and it does not require you to  
+
button that says 'Copy to clipboard', which puts all of the registration code onto your clipboard. Now go to the
−
include the ScriptMaster.fp7 file with your solution. In the module registration screen, click the button that says 'Copy to clipboard',  
+
startup script in your FileMaker solution, add a 'set variable' script step (you can name the variable anything you
−
which puts all of the registration code onto your clipboard. Now go to the startup script in your FileMaker solution, add a 'set variable'  
+
like), and paste in the registration code as the formula to calculate. Now the function will be registered every time
−
script step (you can name the variable anything you like), and paste in the registration code as the formula to calculate. Now the  
+
that your startup script runs. Here's what that script step would look like:  
−
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();" )]
 
  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
−
It is a good idea to check for errors after registering the function, in case there is any problem compiling the Java code.  
+
Java code. See the section below on error reporting, or watch the Youtube movie in this documentation to see an
−
See the section below on error reporting, or watch the Youtube movie in this documentation to see an example of this complete setup.  
+
example of this complete setup. Here is an example that does the same thing as the previous one, but checks for
−
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  
+
errors and displays them to the user in case the function cannot be compiled:  
−
function cannot be compiled:
 
−
 
 
  
 
  If [RegisterGroovy( "GetURLasText( url )"; "new URL(url).getText();" ) = "ERROR"]
 
  If [RegisterGroovy( "GetURLasText( url )"; "new URL(url).getText();" ) = "ERROR"]
Line 84: Line 85:
 
  End If
 
  End If
  
−
 
+
<a name="licensing"> <h3>Licensing and pricing</h3> The ScriptMaster plugin is completely free. You may
−
<a name="licensing">
+
distribute it with your own solution. It would be great if you mention 360Works or ScriptMaster in your documentation
−
<h3>Licensing and pricing</h3>
+
/ about screen, but there is no requirement that you do this. This plugin may be deployed with the Web Publishing
−
The ScriptMaster plugin is completely free. You may distribute it with your own solution. It would be great if you mention  
+
Engine, for scripts that will be called from Instant Web Publishing or Custom Web Publishing. It may also be deployed
−
360Works or ScriptMaster in your documentation / about screen, but there is no requirement that you do this. This plugin may be  
+
on FileMaker Server for use with scripts that are scheduled to run on the server. See the installation section below
−
deployed with the Web Publishing Engine, for scripts that will be called from Instant Web Publishing or Custom Web Publishing.  
+
for more information on how to do this.</p> There is also a ScriptMaster Advanced Edition available. This is
−
It may also be deployed on FileMaker Server for use with scripts that are scheduled to run on the server. See the installation  
+
available for purchase for $95 per developer per year from <a target="360site" href="http://www.360works.com/scriptmaster">http://www.360works.com/scriptmaster</a>.
−
section below for more information on how to do this.</p>
+
If you own a <a target="360site" href="http://www.360works.com/portfolio">360Works Portfolio License</a>, that
−
 
+
includes ScriptMaster Advanced for one developer. Purchasing the advanced edition gives you all the same features as
−
There is also a ScriptMaster Advanced Edition available. This is available for purchase for $95 per developer per year from  
+
the free version, plus three new capabilities:</p> <ul> <li>The Advanced Edition will allow you to easily generate
−
<a target="360site" href="http://www.360works.com/scriptmaster">http://www.360works.com/scriptmaster</a>. If you own a <a target="360site" href="http://www.360works.com/portfolio">360Works Portfolio License</a>, that includes ScriptMaster Advanced for one developer.
+
your own branded plugins. Just register the modules you want and click the 'Make Plugin' button, and you've got a
−
Purchasing the advanced edition gives you all the same features as the free version, plus three new capabilities:</p>
+
plugin with all of your favorite modules pre-compiled into it. You can distribute this generated plugin royalty-free
−
<ul>
+
with all of your custom solutions.</li> <li>The Advanced Edition allows direct access to the FileMaker SQL engine,
−
<li>The Advanced Edition will allow you to easily generate your own branded plugins. Just register the modules you want and click the  
+
which allows you to execute SQL commands directly from any script.</li> <li>The Advanced Edition allows direct access
−
'Make Plugin' button, and you've got a plugin with all of your favorite modules pre-compiled into it. You can distribute this generated  
+
to the FileMaker clipboard, allowing you to read clipboard contents at runtime. You can even modify the clipboard
−
plugin royalty-free with all of your custom solutions.</li>
+
items and then push the modified versions back onto the clipboard.</li> </ul> Plugins created with
−
<li>The Advanced Edition allows direct access to the FileMaker SQL engine, which allows you to execute SQL commands directly from any script.</li>
+
ScriptMaster Advanced cannot be distributed by themselves, for free or commercially. They can only be distributed
−
<li>The Advanced Edition allows direct access to the FileMaker clipboard, allowing you to read clipboard contents at runtime.  
+
with a FileMaker Solution that utilizes the plugin. The FileMaker Solution cannot be just a wrapper or demo of the
−
You can even modify the clipboard items and then push the modified versions back onto the clipboard.</li>
+
plugin functionality, it must be a full-fledged solution in its own right that uses the plugin for additional
−
</ul>
+
functionality.</p> Plugins created with ScriptMaster Advanced can utilize the SQL and Clipboard features. Once
−
 
+
generated, they will never expire. However, the ScriptMaster Advanced plugin itself will not be able to generate new
−
Plugins created with ScriptMaster Advanced cannot be distributed by themselves, for free or commercially. They can only be distributed with a FileMaker
+
plugins after one year until the license key is renewed for an annual cost of $95 per developer.</p> <h3>Tutorial
−
Solution that utilizes the plugin. The FileMaker Solution cannot be just a wrapper or demo of the plugin functionality, it must be a full-fledged solution
+
video</h3> We've created a video showing how to use ScriptMaster. This is a quick (8:15 minute) jump-start showing
−
in its own right that uses the plugin for additional functionality.</p>
+
you how to create a plugin with ScriptMaster Advanced and use it to screen scrape images from a web site.</p> <object
−
 
+
width="640" height="385"><param name="movie" value="http://www.youtube.com/v/dKLJz-Ak9n8&amp;hl=en_US&amp;fs=1?rel=0"></param><param
−
Plugins created with ScriptMaster Advanced can utilize the SQL and Clipboard features. Once generated, they will never expire. However, the ScriptMaster Advanced
+
name="allowFullScreen" value="true"></param><param name="allowscriptaccess" value="always"></param><embed
−
plugin itself will not be able to generate new plugins after one year until the license key is renewed for an annual cost of $95 per developer.</p>
+
src="http://www.youtube.com/v/dKLJz-Ak9n8&amp;hl=en_US&amp;fs=1?rel=0" type="application/x-shockwave-flash"
−
 
+
allowscriptaccess="always" allowfullscreen="true" width="640" height="385"></embed></object> <h3>Loading modules
−
<h3>Tutorial video</h3>
+
from the Internet</h3> ScriptMaster 4 has added a new feature to load ScriptMaster modules from a network URL. You
−
We've created a video showing how to use ScriptMaster. This is a quick (8:15 minute) jump-start showing you how
+
can use the [[#SMLoadJar|SMLoadJar]] function to register all ScriptMaster modules found in the jar file. The jar file can
−
to create a plugin with ScriptMaster Advanced and use it to screen scrape images from a web site.</p>
+
also contain 3rd party classes referenced by the ScriptMaster modules in that jar file. Todd Geist has published his
−
<object width="640" height="385"><param name="movie" value="http://www.youtube.com/v/dKLJz-Ak9n8&amp;hl=en_US&amp;fs=1?rel=0"></param><param name="allowFullScreen" value="true"></param><param name="allowscriptaccess" value="always"></param><embed src="http://www.youtube.com/v/dKLJz-Ak9n8&amp;hl=en_US&amp;fs=1?rel=0" type="application/x-shockwave-flash" allowscriptaccess="always" allowfullscreen="true" width="640" height="385"></embed></object>
+
set of commonly used ScriptMaster modules at this URL:<br> <br> http://www.360works.com/static/ScriptMaster/core/plugin.jar</p>
−
 
+
If you would like to publish your own favorite ScriptMaster modules for others to share, please read the
−
<h3>Loading modules from the Internet</h3>
+
SMLoadJar function description for instructions on this.</p> <h3>Advanced techniques</h3> Your
−
ScriptMaster 4 has added a new feature to load ScriptMaster modules from a network URL. You can use the [[#SMLoadJar|SMLoadJar]] function to register  
+
ScriptMaster functions can reference compiled Java libraries (stored in the .jar format) by using the {@link
−
all ScriptMaster modules found in the jar file. The jar file can also contain 3rd party classes referenced by the ScriptMaster modules in  
+
#SMLoadJar} function. Pass in a container field containing a .jar file, or a URL pointing to a .jar file, and any
−
that jar file. Todd Geist has published his set of commonly used ScriptMaster modules at this URL:<br>
+
scripts you execute will have access to the classes in that .jar. This means you can access libraries like iText (a
−
<br>
+
powerful PDF manipulation library) or qtjava (QuickTime for Java) from within FileMaker. You could also easily write
−
http://www.360works.com/static/ScriptMaster/core/plugin.jar</p>
+
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
−
If you would like to publish your own favorite ScriptMaster modules for others to share, please read the SMLoadJar function  
+
container field.</p> Keep in mind that if you are copying and pasting the function registration into your
−
description for instructions on this.</p>
+
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
−
<h3>Advanced techniques</h3>
+
'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.</p> After a ScriptMaster function executes, you can
−
Your ScriptMaster functions can reference compiled Java libraries (stored in the .jar format) by using the [[#SMLoadJar|SMLoadJar]] function. Pass in a
+
access any of the named variables which were set during execution using the [[#SMGetVariable|SMGetVariable]] function. This can
−
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
+
be very useful for returning multiple output values, similar to setting global variables in a FileMaker script.</p>
−
that .jar. This means you can access libraries like iText (a powerful PDF manipulation library) or qtjava (QuickTime for Java) from within
+
<h3>Getting help</h3> If you get the word 'ERROR' as the result of a ScriptMaster function, be sure to read
−
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 section below on Error reporting for how to get more information on that.</p> Phone and e-mail support for
−
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
+
ScriptMaster are available at our standard hourly rate of $165. There is also a <a
−
field.</p>
+
href="http://fmforums.com/forum/showforum.php?fid/215/" target="fmforums">free ScriptMaster discussion forum</a>
−
 
+
where you can get help from the growing community of ScriptMaster users.</p> If you create your own module
−
Keep in mind that if you are copying and pasting the function registration into your startup script, and that module requires any jar
+
that you think would be useful to others, post it on the fmforums discussion group! If it seems like it will have
−
libraries, you will need to add those jar files to container fields in your solution and use SMLoadJar to load them before registering
+
broad appeal, we'll include it with the next release of ScriptMaster (preference will be given to modules that do not
−
the function. This is not an issue if using the 'register on startup' option with the ScriptMaster.fp7 development file, since that file
+
require 3rd party libraries).</p> <h3>Writing your own modules</h3> In addition to the many existing modules
−
includes all of the jar files needed for the modules that come with ScriptMaster.</p>
+
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 770-234-9293 and let us know what you're looking for, and
−
After a ScriptMaster function executes, you can access any of the named variables which were set during execution using the [[#SMGetVariable|SMGetVariable]]
+
we'll get you an estimate at no charge.</p> The other choice is to do it yourself! We want to start off by
−
function. This can be very useful for returning multiple output values, similar to setting global variables in a FileMaker script.</p>
+
stressing that <b>you can skip the rest of this section</b> 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.
−
<h3>Getting help</h3>
+
However, if the built in modules have stirred your curiosity, you'll be able to take your FileMaker solutions to a
−
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
+
whole new level with the power of Groovy and Java. Because Groovy is cross-platform, modules you create will run on
−
more information on that.</p>
+
both Windows and Mac OS X.</p> 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
−
Phone and e-mail support for ScriptMaster are available at our standard hourly rate of $165. There is also a
+
of the steps about setting up your Java and Groovy environment; that's all taken care of by ScriptMaster).</p>  
−
<a href="http://fmforums.com/forums/forum/118-scriptmaster-by-360-works/" target="fmforums">free ScriptMaster discussion forum</a> where you can get help from the
+
Here are a few tips about using ScriptMaster with FileMaker:</p> In the 'Screen Capture' module, one thing
−
growing community of ScriptMaster users.</p>
+
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
−
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
+
data types than FileMaker, so this can take some getting used to for FileMaker programmers.</p>   In addition
−
will have broad appeal, we'll include it with the next release of ScriptMaster (preference will be given to modules that do not require
+
to setting variables prior to script execution, you can access the FileMaker calculation engine directly from within
−
3rd party libraries).</p>
+
your Groovy script. This is accomplished using the reserved <code>fmpro</code> object. Every Groovy script which is
−
 
+
executed will have an <code>fmpro</code> variable set to an instance of an <code>FMPro</code> object, which has these
−
<h3>Writing your own modules</h3>
+
important methods:</p> <dl> <dt>evaluate(fmcalculation)</dt><dd>Evaluates the supplied FileMaker calculation text,
−
In addition to the many existing modules that come free with ScriptMaster, 360Works is available to create custom modules suited to your
+
returning the result as a String.  The <code>fmcalculation</code> parameter can be any valid FileMaker calculation
−
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
+
string.</dd> <dt>performScript(fileName, scriptName [ , paramString ])</dt><dd>Performs a FileMaker script in the
−
we'll get you an estimate at no charge.</p>
+
current file, passing in the optional <code>paramString</code> as a parameter. Note: <code>fileName</code> is
−
 
+
required.</dd> <dt>merge(template)</dt><dd>Processes some text with merge fields embedded, replacing the merge fields
−
The other choice is to do it yourself! We want to start off by stressing that <b>you can skip the rest of this section</b> if you're not
+
with their evaluated values.  An example of a merge field is <code>&lt;&lt;table::field&gt;&gt;</code>.  If an error
−
interested in learning Groovy or Java. ScriptMaster comes with tons of useful modules that you can use without having to learn a new
+
occurs during evaluation, the field is left as is.</dd> <dt>getContainerStream( fieldName )</dt><dd>Gets an input
−
programming language. However, if the built in modules have stirred your curiosity, you'll be able to take your FileMaker solutions to a
+
stream with bytes from the container field. Be sure to pass in the NAME of the container field, ie
−
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.</p>
+
fmpro.getContainerStream( "Person::Photo" )</dd> <dt>getContainerFileName( fieldName )</dt><dd>Gets the name of the
−
 
+
file stored in a container field. Be sure to pass in the NAME of the container field, ie fmpro.getContainerFileName(
−
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
+
"Person::Photo" ) might return 'jesse.jpg'</dd> <dt>executeSql(sql, columnDelimiter,
−
http://groovy.codehaus.org/Beginners+Tutorial (you can skip all of the steps about setting up your Java and Groovy environment; that's all
+
rowDelimiter)</dt><dd><b>Advanced Edition only: </b>Executes the SQL code in the current FileMaker file. The results
−
taken care of by ScriptMaster).</p>
+
are returned as delimited text, using the provided delimiters.</dd> <dt>executeSqlArray(sql)</dt><dd><b>Advanced
−
 
+
Edition only: </b>Executes the SQL code in the current FileMaker file. The results are returned as a String[][]
−
Here are a few tips about using ScriptMaster with FileMaker:</p>
+
array. If you're going to be processing the results within your Groovy code, this is simpler to work with than
−
In the 'Screen Capture' module, one thing you'll notice is that the Integer.valueOf() calls at the beginning. This is because all
+
getting delimited text.</dd> <dt>getClipboardFormats</dt><dd><b>Advanced Edition only: </b>Gets the list of available
−
ScriptMaster functions are transmitted as text. The Integer.valueOf(someText) translates this into a numeric value. Java is much stricter
+
formats for the current clipboard data.</dd> <dt>getBestFileMakerClipboardFormat</dt><dd><b>Advanced Edition only:
−
about data types than FileMaker, so this can take some getting used to for FileMaker programmers.</p>
+
</b>Gets the format id corresponding to the XML FileMaker clipboard data</dd> <dt>getClipboardContents( format
−
 
+
)</dt><dd><b>Advanced Edition only: </b>Gets the clipboard data for the requested format.</dd>
−
 
+
<dt>setClipboardContents( format, data )</dt><dd><b>Advanced Edition only: </b>Sets the clipboard data for the
−
In addition to setting variables prior to script execution, you can access the FileMaker calculation engine directly from within your Groovy
+
requested format.</dd> <dt>setFileMakerClipboard( data )</dt><dd><b>Advanced Edition only: </b>Sets the clipboard
−
script. This is accomplished using the reserved <code>fmpro</code> object.
+
data from the supplied FileMaker XML data. This will parse the XML data to determine what type of data it is, so a
−
Every Groovy script which is executed will have an <code>fmpro</code> variable set to an instance of an <code>FMPro</code> object,
+
format specifier is not required.</dd> </dl> A script evaluated in ScriptMaster always returns the value of
−
which has these important methods:</p>
+
the last line, or the value which is implicitly returned by the script. This can be any type of Java object.
−
<dl>
+
ScriptMaster does its best to convert this to a FileMaker object.</p> The following conversions occur: <ul>
−
<dt>evaluate(fmcalculation)</dt><dd>Evaluates the supplied FileMaker calculation text, returning the result as a String.  The <code>fmcalculation</code> parameter can be any valid FileMaker calculation string.</dd>
+
<li><code>Strings</code> and <code>Readers</code> are returned as Filemaker <code>TEXT</code> fields, with newline
−
<dt>performScript(fileName, scriptName [ , paramString ])</dt><dd>Performs a FileMaker script in the current file, passing in the optional <code>paramString</code> as a parameter. Note: <code>fileName</code> is required.</dd>
+
characters (<code>\n</code>) converted to carriage returns (<code>\r</code>).  If you are returning a very large
−
<dt>merge(template)</dt><dd>Processes some text with merge fields embedded, replacing the merge fields with their evaluated values.  An example of a merge field is <code>&lt;&lt;table::field&gt;&gt;</code>.  If an error occurs during evaluation, the field is left as is.</dd>
+
block of text, you should return a Reader, which streams in chunks so that it will not run out of memory.</li>
−
<dt>getContainerStream( fieldName )</dt><dd>Gets an input stream with bytes from the container field. Be sure to pass in the NAME of the container field, ie fmpro.getContainerStream( "Person::Photo" )</dd>
 
−
<dt>getContainerFileName( fieldName )</dt><dd>Gets the name of the file stored in a container field. Be sure to pass in the NAME of the container field, ie fmpro.getContainerFileName( "Person::Photo" ) might return 'jesse.jpg'</dd>
 
−
<dt>executeSql(sql, columnDelimiter, rowDelimiter)</dt><dd><b>Advanced Edition only: </b>Executes the SQL code in the current FileMaker file. The results are returned as delimited text, using the provided delimiters.</dd>
 
−
<dt>executeSqlArray(sql)</dt><dd><b>Advanced Edition only: </b>Executes the SQL code in the current FileMaker file. The results are returned as a String[][] array. If you're going to be processing the results within your Groovy code, this is simpler to work with than getting delimited text.</dd>
 
−
<dt>getClipboardFormats</dt><dd><b>Advanced Edition only: </b>Gets the list of available formats for the current clipboard data.</dd>
 
−
<dt>getBestFileMakerClipboardFormat</dt><dd><b>Advanced Edition only: </b>Gets the format id corresponding to the XML FileMaker clipboard data</dd>
 
−
<dt>getClipboardContents( format )</dt><dd><b>Advanced Edition only: </b>Gets the clipboard data for the requested format.</dd>
 
−
<dt>setClipboardContents( format, data )</dt><dd><b>Advanced Edition only: </b>Sets the clipboard data for the requested format.</dd>
 
−
<dt>setFileMakerClipboard( data )</dt><dd><b>Advanced Edition only: </b>Sets the clipboard data from the supplied FileMaker XML data. This will parse the XML data to determine what type of data it is, so a format specifier is not required.</dd>
 
−
</dl>
 
−
 
 
−
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.</p>
 
−
The following conversions occur:
 
−
<ul>
 
−
<li><code>Strings</code> and <code>Readers</code> are returned as Filemaker <code>TEXT</code> fields, with newline characters (<code>\n</code>) converted to carriage returns (<code>\r</code>).  If you are returning a very large block of text, you should return a Reader, which streams in chunks so that it will not run out of memory.</li>
 
 
<li><code>Number</code>s and numeric primitives are returned as FileMaker <code>NUMBER</code> fields</li>
 
<li><code>Number</code>s and numeric primitives are returned as FileMaker <code>NUMBER</code> fields</li>
−
<li><code>Boolean</code> values are returned as a 0 or 1</li>
+
<li><code>Boolean</code> values are returned as a 0 or 1</li> <li><code>File</code> objects are converted to embedded
−
<li><code>File</code> objects are converted to embedded containers</li>
+
containers</li> <li><code>Array</code>s and <code>Collection</code>s are converted to return-separated lists</li>
−
<li><code>Array</code>s and <code>Collection</code>s are converted to return-separated lists</li>
+
<li><code>URL</code>s are converted to embedded containers</li> <li><code>Color</code>s are converted to a string
−
<li><code>URL</code>s are converted to embedded containers</li>
+
like <code>RGB(204,102,255)</code></li> <li><code>RenderedImage</code>, <code>BufferedImage</code> are converted to
−
<li><code>Color</code>s are converted to a string like <code>RGB(204,102,255)</code></li>
+
container images.  If the image has transparency, it is converted to a <code>PNG</code> image. Otherwise it is
−
<li><code>RenderedImage</code>, <code>BufferedImage</code> are converted to container images.  If the image has transparency, it is converted to a <code>PNG</code> image.
+
converted to a <code>JPEG</code>.</li> <li><code>FMType</code> objects are returned as-is.</li> <li>Any other object
−
Otherwise it is converted to a <code>JPEG</code>.</li>
+
is converted to a <code>String</code> and returned as Text.</li> </ul> </p>
−
<li><code>FMType</code> objects are returned as-is.</li>
 
−
<li>Any other object is converted to a <code>String</code> and returned as Text.</li>
 
−
</ul>
 
−
</p>
 
−
 
 
−
 
 
  
 
=360Works Plugin Setup Guides=
 
=360Works Plugin Setup Guides=
Line 221: Line 200:
 
<div id="toc">
 
<div id="toc">
 
*[[#EvaluateGroovy|EvaluateGroovy]] ( groovyScript ) &mdash; Compiles and Evaluates a Groovy script in the foreground.
 
*[[#EvaluateGroovy|EvaluateGroovy]] ( groovyScript ) &mdash; Compiles and Evaluates a Groovy script in the foreground.
−
*[[#RegisterGroovy|RegisterGroovy]] ( signature; script{; key1=value1; key2=value2; ...} ) &mdash; Registers a ScriptMaster script as a custom plugin function.
 
 
*[[#SMCreatePlugin|SMCreatePlugin]] ( pluginName; quadChar; pluginPrefix; helpText; versionString; folderToWriteTo; isCrossPlatform{; is64Bit} ) &mdash; Creates a new plugin that contains all of the currently registered plugin functions.
 
*[[#SMCreatePlugin|SMCreatePlugin]] ( pluginName; quadChar; pluginPrefix; helpText; versionString; folderToWriteTo; isCrossPlatform{; is64Bit} ) &mdash; Creates a new plugin that contains all of the currently registered plugin functions.
 
*[[#SMGetLoadedJars|SMGetLoadedJars]] &mdash; Gets a list of all jars that have been loaded with the {@link #SMLoadJar(com.
 
*[[#SMGetLoadedJars|SMGetLoadedJars]] &mdash; Gets a list of all jars that have been loaded with the {@link #SMLoadJar(com.
−
*[[#SMGetRegisteredModules|SMGetRegisteredModules]] &mdash; Gets a list of all modules that have been registered with the {@link #RegisterGroovy(String, String, String[])} function.
+
*[[#SMGetRegisteredModules|SMGetRegisteredModules]] &mdash; Gets a list of all modules that have been registered with the {@link #RegisterGroovy(String, String, String[])}
−
*[[#SMGetVariable|SMGetVariable]] ( variableName ) &mdash; Returns the value of a named variable which was set in the previously executed call to {@link #EvaluateGroovy(String)}.
+
function.
 +
*[[#SMGetVariable|SMGetVariable]] ( variableName ) &mdash; Returns the value of a named variable which was set in the previously executed call to {@link
 +
#EvaluateGroovy(String)}.
 
*[[#SMLastError|SMLastError]] &mdash; Returns detailed information about the last error generated by this plugin.
 
*[[#SMLastError|SMLastError]] &mdash; Returns detailed information about the last error generated by this plugin.
 
*[[#SMLastStackTrace|SMLastStackTrace]] &mdash; Returns the stack trace of the last generated exception, if any.
 
*[[#SMLastStackTrace|SMLastStackTrace]] &mdash; Returns the stack trace of the last generated exception, if any.
−
*[[#SMLoadJar|SMLoadJar]] ( externalJar ) &mdash; SMLoadJar Loads third-party java libraries and ScriptMaster modules.
 
−
*[[#SMRegister|SMRegister]] ( licenseKey; registeredTo ) &mdash; The SMRegister function is used to register plugins that you generate with ScriptMaster Advanced.
 
−
*[[#SMReset|SMReset]] &mdash; Resets any loaded jars and variables, and clears out all registered functions.
 
−
*[[#SMSetErrorCapture|SMSetErrorCapture]] ( errorCapture ) &mdash; Toggles error dialogs on or off.
 
−
*[[#SMSetVariable|SMSetVariable]] ( variableName ; value ) &mdash; Set a variable to be used in a ScriptMaster Evaluate function call.
 
 
*[[#SMVersion|SMVersion]] &mdash; Returns the version number of the plugin.
 
*[[#SMVersion|SMVersion]] &mdash; Returns the version number of the plugin.
 
</div>
 
</div>
Line 238: Line 213:
 
<div id="EvaluateGroovy"></div>
 
<div id="EvaluateGroovy"></div>
 
==EvaluateGroovy ( groovyScript ) ==
 
==EvaluateGroovy ( groovyScript ) ==
−
Compiles and Evaluates a Groovy script in the foreground.  This is the primary method in ScriptMaster, which is responsible for executing the actual groovy script.
+
Compiles and Evaluates a Groovy script in the foreground.  This is the primary method in ScriptMaster, which is
−
It is recommended that this only be used for testing purposes.  For production use, register your scripts using the [[#RegisterGroovy|RegisterGroovy]] function, which avoids the compilation overhead and is much more convenient.
+
responsible for executing the actual groovy script. It is recommended that this only be used for testing
 +
purposes.  For production use, register your scripts using the [[#RegisterGroovy|RegisterGroovy]] function, which avoids the
 +
compilation overhead and is much more convenient.
  
 
Call [[#SMLastError|SMLastError]] to get a detailed description of the compilation error.
 
Call [[#SMLastError|SMLastError]] to get a detailed description of the compilation error.
  
−
Call [[#SMLastStackTrace|SMLastStackTrace]] to get a detailed description of any exception which occurs during script execution.
+
Call [[#SMLastStackTrace|SMLastStackTrace]] to get a detailed description of any exception which occurs during script
 +
execution.
  
 
<div class="parameters"><strong>Parameters:</strong>
 
<div class="parameters"><strong>Parameters:</strong>
 
<dl><dt><code>groovyScript</code> <dd>a block of groovy/java code
 
<dl><dt><code>groovyScript</code> <dd>a block of groovy/java code
 
</dl></div>
 
</dl></div>
−
<div class="see"><strong>Returns:</strong> the return value of the evaluated expression, or &quot;ERROR&quot; on failure.
+
<div class="see"><strong>Returns:</strong> The return value of the evaluated expression, or &quot;ERROR&quot; on failure.
−
</div>
+
<p>
−
 
+
  <strong>FileMaker Errors:</strong>
−
<div id="RegisterGroovy"></div>
+
<p>
−
==RegisterGroovy ( signature; script{; key1=value1; key2=value2; ...} ) ==
+
<dl> <dd><code>Error 1552</code> - Script has thrown a Runtime Exception</dd> <dd><code>Error 1553</code> -
−
Registers a ScriptMaster script as a custom plugin function. After calling this, you can call the function by name from any calculation dialog.
+
Script does not compile.</dd> </dl>
−
 
 
−
You must pass in a signature for the function being registered.  This is the full signature of the function, including any parameters.  For example:
 
−
 
 
−
Set Variable[$result = RegisterGroovy (
 
−
    "logMessage ( text )" ;
 
−
    "System.out.println(text)"
 
−
)
 
−
 
 
−
Note that the name of the function must not conflict with any pre-existing FileMaker functions.
 
−
 
 
−
The <strong>ScriptMaster.fp7</strong> file included in the ScriptMaster download will take care of registering your ScriptMaster scripts
 
−
as dynamic plugin functions at startup.
 
−
Calling RegisterGroovy twice with the same function name will overwrite the previously registered function.
 
−
The function is uniquely identified by its name (case sensitive).
 
−
You can change the arguments of a function without changing its unique id.
 
−
 
 
−
You can pass in additional parameters to this function in a key=value format. Currently, the only supported additional parameter is 'isGui'.
 
−
By default, all ScriptMaster functions are treated as GUI functions, which means that they may potentially access the drawing functions of the
 
−
operating system. However, there is significant overhead in running a GUI function. If you are positive that a ScriptMaster module does not access the GUI,
 
−
you can pass in a parameter of 'isGui=false' to run it as a non-GUI function. Be aware that this can cause FileMaker to hang if you do access GUI functions
 
−
from the ScriptMaster module, so do not set this parameter unless you are confident that it is correct.
 
−
 
 
−
 
 
−
<div class="parameters"><strong>Parameters:</strong>
 
−
<dl><dt><code>signature</code> <dd>the full signature of the plugin function, as it appears in the FileMaker list of functions.
 
−
<dt><code>script</code> <dd>the actual script.
 
−
</dl></div>
 
−
<div class="see"><strong>Returns:</strong> 1 if the function is successfully registered, "ERROR" if an error occurs.
 
 
</div>
 
</div>
  
 
<div id="SMCreatePlugin"></div>
 
<div id="SMCreatePlugin"></div>
 
==SMCreatePlugin ( pluginName; quadChar; pluginPrefix; helpText; versionString; folderToWriteTo; isCrossPlatform{; is64Bit} ) ==
 
==SMCreatePlugin ( pluginName; quadChar; pluginPrefix; helpText; versionString; folderToWriteTo; isCrossPlatform{; is64Bit} ) ==
−
Creates a new plugin that contains all of the currently registered plugin functions. This feature is only available with the  
+
Creates a new plugin that contains all of the currently registered plugin functions. This feature is only
−
Advanced Edition of ScriptMaster. You must be online with working internet access to use this feature.
+
available with the Advanced Edition of ScriptMaster. You must be online with working internet access to use this
 +
feature.
  
 
<div class="parameters"><strong>Parameters:</strong>
 
<div class="parameters"><strong>Parameters:</strong>
 
<dl><dt><code>pluginName</code> <dd>The name of the new plugin. For example, 'My Plugin'
 
<dl><dt><code>pluginName</code> <dd>The name of the new plugin. For example, 'My Plugin'
−
<dt><code>quadChar</code> <dd>4 alphanumeric characters that uniquely identify your plugin. Use your best guess to come up with a quadChar that is unlikely to be the same as something else, ie. 'mHz7'. Users will never see this quadChar.
+
<dt><code>quadChar</code> <dd>4 alphanumeric characters that uniquely identify your plugin. Use your best guess to come
−
<dt><code>pluginPrefix</code> <dd>A piece of text that will appear before before standard functions. For example, if your plugin prefix is 'ABC', then you will have plugin functions 'ABCVersion', 'ABCLastError', and 'ABCRegister' instead of 'SMVersion', 'SMLastError', and 'SMRegister'.
+
                        up with a quadChar that is unlikely to be the same as something else, ie. 'mHz7'. Users
−
<dt><code>helpText</code> <dd>The text that should appear in the plugin preferences dialog when somebody selects your plugin, for example 'This plugin has many useful networking functions'
+
                        will never see this quadChar.
−
<dt><code>versionString</code> <dd>This should be a decimal value that appears after the help text in the plugin preferences, for example '1.02'
+
<dt><code>pluginPrefix</code> <dd>A piece of text that will appear before before standard functions. For example, if your
−
<dt><code>folderToWriteTo</code> <dd>The folder where the plugins should be written to. A MAC and/or WIN subfolder will be created, depending on the crossPlatform setting.
+
                        plugin prefix is 'ABC', then you will have plugin functions 'ABCVersion', 'ABCLastError',
−
<dt><code>crossPlatform</code> <dd>Pass in a 0 to only create a plugin for the current platform (ie. a Windows plugin if you are running on Windows, and a Mac plugin if you are running on Mac OS X). If you pass in a 1, you will be prompted for the location of the plugin for the other platform, and then both a Mac and Windows plugin will be created.
+
                        and 'ABCRegister' instead of 'SMVersion', 'SMLastError', and 'SMRegister'.
−
<dt><code>is64Bit</code> <dd>Optional parameter. Pass in a 0 to create a 32-bit plugin or a 1 to spawn a file chooser dialog used to select the 64-bit SM plugin needed to create a 64-bit plugin. Only applies when building plugins on Windows.
+
<dt><code>helpText</code> <dd>The text that should appear in the plugin preferences dialog when somebody selects your
 +
                        plugin, for example 'This plugin has many useful networking functions'
 +
<dt><code>versionString</code> <dd>This should be a decimal value that appears after the help text in the plugin preferences,
 +
                        for example '1.02'
 +
<dt><code>folderToWriteTo</code> <dd>The folder where the plugins should be written to. A MAC and/or WIN subfolder will be
 +
                        created, depending on the crossPlatform setting.
 +
<dt><code>crossPlatform</code> <dd>Pass in a 0 to only create a plugin for the current platform (ie. a Windows plugin if you
 +
                        are running on Windows, and a Mac plugin if you are running on Mac OS X). If you pass in a
 +
                        1, you will be prompted for the location of the plugin for the other platform, and then
 +
                        both a Mac and Windows plugin will be created.
 +
<dt><code>is64Bit</code> <dd>Optional parameter. Pass in a 0 to create a 32-bit plugin or a 1 to spawn a file chooser
 +
                        dialog used to select the 64-bit SM plugin needed to create a 64-bit plugin. Only applies
 +
                        when building plugins on Windows.
 
</dl></div>
 
</dl></div>
−
<div class="see"><strong>Returns:</strong> The license key to use for registering the generated plugin, or the word 'ERROR' if something went wrong. In this case, use the SMLastError function to get more details about what went wrong.
+
<div class="see"><strong>Returns:</strong> The license key to use for registering the generated plugin, or the word 'ERROR' if something went wrong.
 +
In this case, use the SMLastError function to get more details about what went wrong.
 +
<p>
 +
<strong>FileMaker Errors:</strong>
 +
<p>
 +
<dl> <dd><code>Error 1552</code> - SMCreatePlugin was called with an empty plugin name.</dd> <dd><code>Error
 +
1553</code> - QuadChar is not exactly 4 characters in length.</dd> <dd><code>Error 1554</code> - Version String
 +
is empty.</dd> <dd><code>Error 1555</code> - Plugin Output folder is empty.</dd> <dd><code>Error 1556</code> -
 +
Plugin generation failed.</dd> </dl>
 
</div>
 
</div>
  
 
<div id="SMGetLoadedJars"></div>
 
<div id="SMGetLoadedJars"></div>
 
==SMGetLoadedJars==
 
==SMGetLoadedJars==
−
Gets a list of all jars that have been loaded with the [[#SMLoadJar|SMLoadJar]] function. This list is
+
Gets a list of all jars that have been loaded with the [[#SMLoadJar|SMLoadJar]] function.
−
cleared out when [[#SMReset|SMReset]] is called.
+
This list is cleared out when [[#SMReset|SMReset]] is called.
  
  
Line 311: Line 282:
 
<div id="SMGetRegisteredModules"></div>
 
<div id="SMGetRegisteredModules"></div>
 
==SMGetRegisteredModules==
 
==SMGetRegisteredModules==
−
Gets a list of all modules that have been registered with the [[#RegisterGroovy|RegisterGroovy]] function. This list is
+
Gets a list of all modules that have been registered with the [[#RegisterGroovy|RegisterGroovy]]
−
cleared out when [[#SMReset|SMReset]] is called.
+
function. This list is cleared out when [[#SMReset|SMReset]] is called.
  
  
Line 318: Line 289:
 
<div id="SMGetVariable"></div>
 
<div id="SMGetVariable"></div>
 
==SMGetVariable ( variableName ) ==
 
==SMGetVariable ( variableName ) ==
−
Returns the value of a named variable which was set in the previously executed call to [[#EvaluateGroovy|EvaluateGroovy]].
+
Returns the value of a named variable which was set in the previously executed call to {@link
−
This can be very useful if your custom script needs to return multiple values, or for debugging purposes.
+
#EvaluateGroovy(String)}. This can be very useful if your custom script needs to return multiple values, or for
−
You can set any named variable within your script and retrieve the value of that value after evaluation has been completed.
+
debugging purposes. You can set any named variable within your script and retrieve the value of that value after
 +
evaluation has been completed.
  
  
Line 327: Line 299:
 
</dl></div>
 
</dl></div>
 
<div class="see"><strong>Returns:</strong> the value which was assigned to the named variable during the last script execution.
 
<div class="see"><strong>Returns:</strong> the value which was assigned to the named variable during the last script execution.
 +
<p>
 +
<strong>FileMaker Errors:</strong>
 +
<p>
 +
<dl> <dd><code>Error 1552</code> - {@link #SMGetVariable(String)} was called before {@link
 +
#EvaluateGroovy(String)}.</dd> </dl>
 
</div>
 
</div>
  
 
<div id="SMLastError"></div>
 
<div id="SMLastError"></div>
 
==SMLastError==
 
==SMLastError==
−
Returns detailed information about the last error generated by this plugin. If another plugin function returns the
+
Returns detailed information about the last error generated by this plugin. If another plugin function returns
−
text "ERROR", call this function to get a user-presentable description of what went wrong.
+
the text "ERROR", call this function to get a user-presentable description of what went wrong.
  
 
<div class="see"><strong>Returns:</strong> Error text, or an empty string if there was no error.
 
<div class="see"><strong>Returns:</strong> Error text, or an empty string if there was no error.
Line 339: Line 316:
 
<div id="SMLastStackTrace"></div>
 
<div id="SMLastStackTrace"></div>
 
==SMLastStackTrace==
 
==SMLastStackTrace==
−
Returns the stack trace of the last generated exception, if any.
+
Returns the stack trace of the last generated exception, if any. This can be handy for troubleshooting cryptic
−
This can be handy for troubleshooting cryptic error messages, when [[#SMLastError|SMLastError]] does not return enough info.
+
error messages, when [[#SMLastError|SMLastError]] does not return enough info.
  
 
<div class="see"><strong>Returns:</strong> the stack trace of the last execution.
 
<div class="see"><strong>Returns:</strong> the stack trace of the last execution.
−
</div>
 
−
 
−
<div id="SMLoadJar"></div>
 
−
==SMLoadJar ( externalJar ) ==
 
−
SMLoadJar Loads third-party java libraries and ScriptMaster modules. All Java classes found in the jar (Java Archive)
 
−
file will be loaded into ScriptMaster, where they can then be referenced by ScriptMaster modules.
 
−
For example, the e-mail modules in ScriptMaster use the mail.jar and activation.jar files.
 
−
Note that the ScriptMaster.fp7 file keeps tracks of which jars are needed for the  modules that ship with it, and calls SMLoadJar for them
 
−
automatically.
 
−
 
−
A jar file can also contain ScriptMaster modules, which will be registered when this function is used.
 
−
Since jar files can be loaded from the network (see below), this allows you to use ScriptMaster functions in your solution
 
−
without needing to explicitly register any functions at all in your solution.
 
−
 
−
Here is a list of the publicly available ScriptMaster modules (currently only one, more will be added):
 
−
<ul>
 
−
<li>http://www.360works.com/static/ScriptMaster/core/plugin.jar</li>
 
−
</ul>
 
−
 
−
To create a jar file that can be loaded with this function, use the [[#SMCreatePlugin|SMCreatePlugin]] feature to create a Mac plugin with the functions that
 
−
you want. Then upload the plugin file to
 
−
[http://www.360works.com/upload/ http://www.360works.com/upload/]. We will create a signed jar file and send it back
 
−
to you, usually within 24 hours. Once you receive that jar file, you can then register the functions in that jar file using this SMLoadJar function.
 
−
 
−
To add your own ScriptMaster functions to the list of publicly available modules, please contact 360Works.
 
−
 
−
 
−
There are three methods of loading the driver .jar file: from a URL, from a container field, or  from a file on the hard drive.
 
−
<h4>Loading a custom .jar file from a URL</h4>
 
−
You can load a jar file which is accessible on the network or on the local file system by passing a URL parameters as the <code>externalJar</code> parameter.
 
−
The URL should be of the form <code>http://example.org/path/to/my.jar</code> or <code>file:///path/to/my.jar</code>.
 
−
 
−
<h4>Loading a custom .jar file from a container field</h4>
 
−
 
−
You can embed any java .jar file into a container field in your FileMaker solution, and load the .jar from there.
 
−
<h4>Loading a custom .jar file from a file on the hard drive</h4>
 
−
You can pass in an OS-specific path, like C:\Documents and Settings\Joe\My.jar or /Users/Joe/My.jar to load the jar from your hard drive.
 
−
 
−
<h4>Caching Behavior</h4>
 
−
Jars are cached according to their name.  If you register two files with the same name, the second will not be registered.
 
−
The jar file will remain registered until you call [[#SMReset|SMReset]] or quit FileMaker.
 
−
 
−
<div class="parameters"><strong>Parameters:</strong>
 
−
<dl></dl></div>
 
−
<div class="see"><strong>Returns:</strong> 1 if the jar was loaded successfully, or an error message if the jar could not be loaded.
 
−
</div>
 
−
 
−
<div id="SMRegister"></div>
 
−
==SMRegister ( licenseKey; registeredTo ) ==
 
−
The SMRegister function is used to register plugins that you generate with ScriptMaster Advanced. It will only appear when you are using plugins generated
 
−
with ScriptMaster Advanced, it is not used to register the ScriptMaster Advanced plugin itself - do that in the plugin preferences dialog
 
−
(in FileMaker Application preferences / plugins ). It will be renamed in your generated plugin based on the plugin prefix that you use for [[#SMCreatePlugin|SMCreatePlugin]] , so if your
 
−
plugin prefix is 'ABC', this function will be called 'ABCRegister' in the generated plugin.
 
−
 
−
If you don't call this function for your generated plugins, they will work for 2 hours every time you
 
−
start FileMaker. Once you call the register function, the generated plugin will no longer stop working after 2 hours. However, this registration does not persist after quitting
 
−
FileMaker, so we recommend that you put the registration function call in the startup script of your solution, so it will be registered every time you open a solution that uses
 
−
the generated plugin.
 
−
 
−
You do not need an internet connection to call this function.
 
−
 
−
<div class="parameters"><strong>Parameters:</strong>
 
−
<dl><dt><code>licenseKey</code> <dd>The license key returned by the SMCreatePlugin function
 
−
<dt><code>registeredTo</code> <dd>The name of your company, as you entered onto the web form when you ordered ScriptMaster Advanced.
 
−
</dl></div>
 
−
<div class="see"><strong>Returns:</strong> 1 if successful, or the word 'ERROR' if something goes wrong. Use SMLastError to get the description of the last error.
 
−
</div>
 
−
 
−
<div id="SMReset"></div>
 
−
==SMReset==
 
−
Resets any loaded jars and variables, and clears out all registered functions. This is only needed if you are reloading jar files.
 
−
 
−
<div class="see"><strong>Returns:</strong> 1
 
−
</div>
 
−
 
−
<div id="SMSetErrorCapture"></div>
 
−
==SMSetErrorCapture ( errorCapture ) ==
 
−
Toggles error dialogs on or off. When something unexpected happens, the plug-in will pop up a dialog displaying the error message. This makes it easy to see what went wrong. However, in some cases, you (the developer) may prefer to show your own message to the user, or possibly not show a message at all. In that case, you can call SMSetErrorCapture with a parameter of true. That will suppress the error dialog from appearing to the user.
 
−
 
−
<div class="parameters"><strong>Parameters:</strong>
 
−
<dl><dt><code>errorCapture</code> <dd>set to true to suppress the default popups.
 
−
</dl></div>
 
−
 
−
 
−
<div id="SMSetVariable"></div>
 
−
==SMSetVariable ( variableName ; value ) ==
 
−
Set a variable to be used in a ScriptMaster Evaluate function call.  The next script evaluated will have access to this named variable.
 
−
 
−
Note that the value will always be converted to a String.  If you need to use this as some other object type (date, etc) you are responsible for converting it within your script.
 
−
 
−
All variables are cleared after every call to an Evaluate function.
 
−
Setting a variable also clears the named variables from the previous script execution.  If a script dealing with memory-intensive objects has been completed, it's a good idea to set a dummy variable to free up this memory.
 
−
 
−
<div class="parameters"><strong>Parameters:</strong>
 
−
<dl><dt><code>variableName</code> <dd>the name of the variable being set
 
−
<dt><code>value</code> <dd>the value of the variable being set
 
−
</dl></div>
 
−
<div class="see"><strong>Returns:</strong> '1'
 
 
</div>
 
</div>
  

Latest revision as of 21:09, 27 November 2017

360Works ScriptMaster User Guide

Introduction

ScriptMaster is a free, general-purpose, modular plugin. It includes modules for file manipulation (reading, writing, copying, deleting, zipping/unzipping, and moving files on the hard drive); downloading URLs and submitting forms online; XML Web Services; shell scripting; and many others including screen capture, encryption, SQL access and clipboard access. 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 like FileMaker custom functions: You pass in some inputs and get back 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, install the ScriptMaster plugin by copying it into your FileMaker extensions directory (complete installation instructions can be found below). Then open the ScriptMaster.fp7 file that comes with it. At the top, click on 'ScriptMaster Modules' which will show you a list of all of the modules that come with ScriptMaster listed in order by Category. To try one out, click on it in the list view. 'Screen Capture' under the 'Containers' Category is a good one to start with. This module will take a picture of some section of your screen and store it into a container field in FileMaker. You supply parameters for left, top, width, and height, which tells the module which section of your screen to capture. This is a good module 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 'Run Script' button with the green arrow to run the module, which will run the module based on the values set for the input variables. After you run this, you should see a screen shot in the result area at the bottom of the screen (click on 'Enlarge' to see the full screen shot). Experiment with changing the inputs (left, top, width, and height) to see the result, and try out some of the other modules that come with ScriptMaster.

Registering Modules As Functions

The 'Run 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 FileMaker solution. For that, we'll talk about registering this module as a function, which makes the module appear in your list of available FileMaker functions. Because it compiles the code, it will also run much faster as a registered function than by using the 'Run Script' button. To register a module, simply click the 'Register Function' button at the bottom of any module's screen. This compiles the code for the module, adds it to the list of available FileMaker functions, and takes you to a screen showing that the module has been registered successfully. You can see your registered ScriptMaster functions anywhere you'd get a calculation dialog in FileMaker (such as a calculation field or a 'set variable' script step) by 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.

<img src="doc_images/ExternalFunctions.png" />

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 three options for

registering ScriptMaster modules every time you open your solution file.

The first option requires

ScriptMaster Advanced Edition. This is available for purchase for $95 per developer per year from <a target="360site" href="http://www.360works.com/scriptmaster">http://www.360works.com/scriptmaster</a>, and is included in the <a target="360site" href="http://www.360works.com/portfolio">360Works Portfolio License Bundle</a>. See the <a href="#licensing">licensing section</a> for more details. With the Advanced Edition, click the 'plugin generation' button from the registration screen or the top of any other screen. This will create a new plugin that you can name whatever you want and distribute to your customers along with your FileMaker solutions royalty-free. This plugin is completely self-contained, and does not require either the ScriptMaster plugin or the ScriptMaster.fp7 FileMaker

file.

<img src="doc_images/GeneratedPlugin.png" />

The second option 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"]

The third option is the most complex, but it does not require ScriptMaster Advanced Edition, and it does

not require you to include the ScriptMaster.fp7 file with your solution. In the module registration screen, click the button that says 'Copy to clipboard', which puts all of the registration code onto your clipboard. Now go to the startup script in your FileMaker 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

<a name="licensing">

Licensing and 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.

There is also a ScriptMaster Advanced Edition available. This is

available for purchase for $95 per developer per year from <a target="360site" href="http://www.360works.com/scriptmaster">http://www.360works.com/scriptmaster</a>. If you own a <a target="360site" href="http://www.360works.com/portfolio">360Works Portfolio License</a>, that includes ScriptMaster Advanced for one developer. Purchasing the advanced edition gives you all the same features as

the free version, plus three new capabilities:

  • The Advanced Edition will allow you to easily generate

    your own branded plugins. Just register the modules you want and click the 'Make Plugin' button, and you've got a plugin with all of your favorite modules pre-compiled into it. You can distribute this generated plugin royalty-free

    with all of your custom solutions.
  • The Advanced Edition allows direct access to the FileMaker SQL engine, which allows you to execute SQL commands directly from any script.
  • The Advanced Edition allows direct access to the FileMaker clipboard, allowing you to read clipboard contents at runtime. You can even modify the clipboard items and then push the modified versions back onto the clipboard.

Plugins created with

ScriptMaster Advanced cannot be distributed by themselves, for free or commercially. They can only be distributed with a FileMaker Solution that utilizes the plugin. The FileMaker Solution cannot be just a wrapper or demo of the plugin functionality, it must be a full-fledged solution in its own right that uses the plugin for additional

functionality.

Plugins created with ScriptMaster Advanced can utilize the SQL and Clipboard features. Once

generated, they will never expire. However, the ScriptMaster Advanced plugin itself will not be able to generate new

plugins after one year until the license key is renewed for an annual cost of $95 per developer.

Tutorial video

We've created a video showing how to use ScriptMaster. This is a quick (8:15 minute) jump-start showing you how to create a plugin with ScriptMaster Advanced and use it to screen scrape images from a web site.

<object

width="640" height="385"><param name="movie" value="http://www.youtube.com/v/dKLJz-Ak9n8&hl=en_US&fs=1?rel=0"></param><param name="allowFullScreen" value="true"></param><param name="allowscriptaccess" value="always"></param><embed src="http://www.youtube.com/v/dKLJz-Ak9n8&hl=en_US&fs=1?rel=0" type="application/x-shockwave-flash"

allowscriptaccess="always" allowfullscreen="true" width="640" height="385"></embed></object>

Loading modules from the Internet

ScriptMaster 4 has added a new feature to load ScriptMaster modules from a network URL. You

can use the SMLoadJar function to register all ScriptMaster modules found in the jar file. The jar file can also contain 3rd party classes referenced by the ScriptMaster modules in that jar file. Todd Geist has published his

set of commonly used ScriptMaster modules at this URL:

http://www.360works.com/static/ScriptMaster/core/plugin.jar

If you would like to publish your own favorite ScriptMaster modules for others to share, please read the

SMLoadJar function description for instructions on this.

Advanced techniques

Your

ScriptMaster functions can reference compiled Java libraries (stored in the .jar format) by using the {@link

  1. 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 $165. There is also a <a href="http://fmforums.com/forum/showforum.php?fid/215/" target="fmforums">free ScriptMaster discussion forum</a>

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).

Writing your own 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 770-234-9293 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.
getContainerStream( fieldName )
Gets an input stream with bytes from the container field. Be sure to pass in the NAME of the container field, ie fmpro.getContainerStream( "Person::Photo" )
getContainerFileName( fieldName )
Gets the name of the file stored in a container field. Be sure to pass in the NAME of the container field, ie fmpro.getContainerFileName( "Person::Photo" ) might return 'jesse.jpg'
executeSql(sql, columnDelimiter, rowDelimiter)
Advanced Edition only: Executes the SQL code in the current FileMaker file. The results are returned as delimited text, using the provided delimiters.
executeSqlArray(sql)
Advanced Edition only: Executes the SQL code in the current FileMaker file. The results are returned as a String[][] array. If you're going to be processing the results within your Groovy code, this is simpler to work with than getting delimited text.
getClipboardFormats
Advanced Edition only: Gets the list of available formats for the current clipboard data.
getBestFileMakerClipboardFormat
Advanced Edition only: Gets the format id corresponding to the XML FileMaker clipboard data
getClipboardContents( format )
Advanced Edition only: Gets the clipboard data for the requested format.
setClipboardContents( format, data )
Advanced Edition only: Sets the clipboard data for the requested format.
setFileMakerClipboard( data )
Advanced Edition only: Sets the clipboard data from the supplied FileMaker XML data. This will parse the XML data to determine what type of data it is, so a format specifier is not required.

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, which streams in chunks so that it will not run out of memory.
  • 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.

360Works Plugin Setup Guides

See Plugins_101 for Error reporting, installation, registration, and more.

Function Summary

  • EvaluateGroovy ( groovyScript ) — Compiles and Evaluates a Groovy script in the foreground.
  • SMCreatePlugin ( pluginName; quadChar; pluginPrefix; helpText; versionString; folderToWriteTo; isCrossPlatform{; is64Bit} ) — Creates a new plugin that contains all of the currently registered plugin functions.
  • SMGetLoadedJars — Gets a list of all jars that have been loaded with the {@link #SMLoadJar(com.
  • SMGetRegisteredModules — Gets a list of all modules that have been registered with the {@link #RegisterGroovy(String, String, String[])}
function.
  • SMGetVariable ( variableName ) — Returns the value of a named variable which was set in the previously executed call to {@link
#EvaluateGroovy(String)}.
  • SMLastError — Returns detailed information about the last error generated by this plugin.
  • SMLastStackTrace — Returns the stack trace of the last generated exception, if any.
  • SMVersion — Returns the version number of the plugin.

Function Detail

EvaluateGroovy ( groovyScript )

Compiles and Evaluates a Groovy script in the foreground. This is the primary method in ScriptMaster, which is responsible for executing the actual groovy script. It is recommended that this only be used for testing purposes. For production use, register your scripts using the RegisterGroovy function, which avoids the compilation overhead and is much more convenient.

Call SMLastError to get a detailed description of the compilation error.

Call SMLastStackTrace to get a detailed description of any exception which occurs during script execution.

Parameters:
groovyScript
a block of groovy/java code
Returns: The return value of the evaluated expression, or "ERROR" on failure.

FileMaker Errors:

Error 1552 - Script has thrown a Runtime Exception
Error 1553 - Script does not compile.

SMCreatePlugin ( pluginName; quadChar; pluginPrefix; helpText; versionString; folderToWriteTo; isCrossPlatform{; is64Bit} )

Creates a new plugin that contains all of the currently registered plugin functions. This feature is only available with the Advanced Edition of ScriptMaster. You must be online with working internet access to use this feature.

Parameters:
pluginName
The name of the new plugin. For example, 'My Plugin'
quadChar
4 alphanumeric characters that uniquely identify your plugin. Use your best guess to come up with a quadChar that is unlikely to be the same as something else, ie. 'mHz7'. Users will never see this quadChar.
pluginPrefix
A piece of text that will appear before before standard functions. For example, if your plugin prefix is 'ABC', then you will have plugin functions 'ABCVersion', 'ABCLastError', and 'ABCRegister' instead of 'SMVersion', 'SMLastError', and 'SMRegister'.
helpText
The text that should appear in the plugin preferences dialog when somebody selects your plugin, for example 'This plugin has many useful networking functions'
versionString
This should be a decimal value that appears after the help text in the plugin preferences, for example '1.02'
folderToWriteTo
The folder where the plugins should be written to. A MAC and/or WIN subfolder will be created, depending on the crossPlatform setting.
crossPlatform
Pass in a 0 to only create a plugin for the current platform (ie. a Windows plugin if you are running on Windows, and a Mac plugin if you are running on Mac OS X). If you pass in a 1, you will be prompted for the location of the plugin for the other platform, and then both a Mac and Windows plugin will be created.
is64Bit
Optional parameter. Pass in a 0 to create a 32-bit plugin or a 1 to spawn a file chooser dialog used to select the 64-bit SM plugin needed to create a 64-bit plugin. Only applies when building plugins on Windows.
Returns: The license key to use for registering the generated plugin, or the word 'ERROR' if something went wrong. 
In this case, use the SMLastError function to get more details about what went wrong.

FileMaker Errors:

Error 1552 - SMCreatePlugin was called with an empty plugin name.
Error 1553 - QuadChar is not exactly 4 characters in length.
Error 1554 - Version String is empty.
Error 1555 - Plugin Output folder is empty.
Error 1556 - Plugin generation failed.

SMGetLoadedJars

Gets a list of all jars that have been loaded with the SMLoadJar function. This list is cleared out when SMReset is called.


SMGetRegisteredModules

Gets a list of all modules that have been registered with the RegisterGroovy function. This list is cleared out when SMReset is called.


SMGetVariable ( variableName )

Returns the value of a named variable which was set in the previously executed call to {@link

  1. EvaluateGroovy(String)}. This can be very useful if your custom script needs to return multiple values, or for

debugging purposes. You can set any named variable within your script and retrieve the value of that value after evaluation has been completed.


Parameters:
variableName
the name of the variable whose value is being gotten.
Returns: the value which was assigned to the named variable during the last script execution.

FileMaker Errors:

Error 1552 - {@link #SMGetVariable(String)} was called before {@link #EvaluateGroovy(String)}.

SMLastError

Returns detailed information about the last error generated by this plugin. If another plugin function returns the text "ERROR", call this function to get a user-presentable description of what went wrong.

Returns: Error text, or an empty string if there was no error.

SMLastStackTrace

Returns the stack trace of the last generated exception, if any. This can be handy for troubleshooting cryptic error messages, when SMLastError does not return enough info.

Returns: the stack trace of the last execution.

SMVersion

Returns the version number of the plugin.

Returns: a string representation of the version number
Retrieved from "http://docs.360works.com/index.php?title=360Works_ScriptMaster/Documentation&oldid=2415"