Plug-Ins 101

From 360Works Product Documentation Wiki
Jump to: navigation, search

This is a guide is for FileMaker users and developers who are new to using plug-ins with FileMaker Pro and FileMaker Server. It explains concepts that are applicable to all 360Works plug-ins, and to many FileMaker plug-ins in general.

The FileMaker Plug-In dialog showing three 360Works plug-ins, with one disabled

Contents

What is a plug-in?

A plug-in is a file that can be installed to add new external functions to the calculation dialog in FileMaker. In general, plug-ins do NOT add new script steps or change the overall behavior of FileMaker Pro. They also do not stand alone, and are instead only used to extend FileMaker's capabilities. A plug-in's functionality can range from improving FileMaker's ability to send emails to allowing FileMaker to run custom Groovy code at will. By allowing developers to expand the functionality of FileMaker without changing its core structure, plug-ins ensure that FileMaker maintains its broad user group while meeting very specific needs. Without plug-ins, users would need to purchase additional stand-alone software that may not interface with existing FileMaker databases. By utilizing FileMaker's standard functions to perform non-standard tasks, plug-ins help ensure that your information is accessible, organized, and integrated.

Getting Started with Plug-Ins

Plug-in Installation

Refer to our Plug-In Installation page.

(For further reference, check FileMaker's official plug-in installation docs)

Licensing

Please refer to our Plug-In Licensing page.

Using Plug-ins

Think of plug-ins as the tools you need to build a specific solution within FileMaker. For example, purchasing 360Works’ Plastic plug-in will not give you an out of the box point of sale system. However, using the tools that Plastic provides and using FileMaker’s existing functions will allow you to build your system from the ground up.

Creating Scripts, Calling Functions, and Setting Variables

Scripts are commands that cause FileMaker to perform specific tasks. They can be simple or complex, made of variable script steps. Script steps are generally composed of a Function, which defines the action that the script performs, and Variables, which define the parameters of the action. As plug-ins are used within FileMaker, you can use scripts to control the actions of plugins.

To create a script, open the script manager from the menu bar of your FileMaker database. This opens the script manager, where you can create new scripts or edit existing ones using the buttons in the lower left. These buttons open the script editor, which show all of the steps in a script. On the left is a list of all possible scripts. These scripts define how the script will perform an action. Double clicking any of these will add the step to your script. To further define the function and parameters of the script, select a script step in the editor window, then click the “Specify” button.


Plugins10113.png



This brings you to the Specify Calculation window. On the left will be a list of all functions accessible to FileMaker. These functions provide the actions that your script will perform. To access the Functions associated with Plug-ins, select “External Functions” in the View drop-down. Adding a function to a script step is known as “calling” that function.


The second part of a script step is known as a variable. This tells the script where to perform the function, and gives the authorization to access this location. Variables are set in the parentheses behind the function in the Specify Calculation window.


Plugins10114.png



Entering this information is known as setting a variable. This process will allow you to write a script calling a specific function with set variables.


Error Handling/Reporting

When something unexpected happens, the plug-in will pop up a dialog showing what the error message is. 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 <<setErrorCaptureFunctionName>> with a parameter of true. That will suppress the error dialog from appearing to the user.

Whether or not you suppress the error dialogs, a plugin function will return the word ERROR if something goes wrong. It's a good idea to put your plugin functions in an 'If' statement so that you don't execute a bunch of script steps after something has gone wrong. If you'd like for your script to get the error message, you can get that by calling the <<lastErrorFunctionName>> function.

Here is an example of basic error reporting:

Set Variable [ $result = MyPluginFunction("x" ; "y" ; "z") ]
If [ $result = "ERROR" ]
    Exit Script[ "Error occurred: " & <<lastErrorFunctionName>> ]
Else
    ... do more stuff here ...
End If

Chaining Multiple Functions Together

Since the string "ERROR" evaluates to false when evaluated by FileMaker, and most plugin functions return a 1 when successful, you can chain multiple dependent plugin operations together using the "and" operator. However, in this case the result will be a 1 or a 0, not "ERROR". For example:

// chain multiple calls together
// if any of the functions fail, the calculation will
// short-circuit with a result of <code>false</code>,
// 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: " & <<lastErrorFunctionName>> ]
End If

Note: the above only works for plugin functions which return 1 on success! Check the documentation for each function used in this manner.

Additional Error Checking - Plugin not installed

If a plugin is not installed correctly, calls to a plugin function will return "?". As part of your startup script, you should check for this occurrence and display a warning accordingly that the plugin needs to be installed. Note: when treated as a boolean true/false value, FileMaker will treat ? as true.

Troubleshooting/Common Plugin Issues

The plugin file is installed in the correct directory, but FileMaker doesn't load it

Be sure the plugin file is not encrypted and not a hidden file. FileMaker will skip loading plugins that are hidden or encrypted.

"?" failed to initialize

This generally means there has been a mismatch with the version of Java you are using.

This section focuses on FileMaker Pro and Pro Advanced, but the same rules apply to Server concerning 32 vs 64 bit. To find out which version of the plugin you should be using, see the table here:
Plugin_installation

Mac

For Mac users, you need the Apple maintained version of Java, available here:
https://support.apple.com/kb/dl1572?locale=en_US

Windows

Pre-FileMaker Pro 14

All version of FileMaker Pro prior to 14 were 32 bit, follow the instructions below for 32-bit FileMaker 14

FileMaker Pro 14

For Windows users, things have gotten a little more complex with the release of FileMaker 14. There is now a 32-bit and a 64-bit version of FileMaker 14.

You need to have the corresponding plugin, and version of Java.

For 32-bit FileMaker Pro 14

360Works Plugin.fmx (the extension is .fmx)
32-bit version of Java, available here:
http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
Windows x86 is the one you want

For 64-bit FileMaker Pro 14

360Works Plugin.fmx64 (notice the extension is .fmx64)
64-bit version of Java, available here:
http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
Windows x64 is the one you want

Getting Help

Individual Plug-in Support

Many questions about 360Works plugins can be answered in one of two places: the plugin documentation or the product support wiki. To access the documentation, you can either view the documentation.html file within the plugin folder, or visit http://www.360works.com/products. Choose your product from the left sidebar, then click the “View Documentation” button.

You can also check our Product Support Wiki for answers to common plugin questions or visit the FMForums 360Works section. If your question doesn’t appear in the forums, create a new post and a support representative will respond.


Plugins10116.png


Contacting 360Works

Sometimes you may have questions that the documentation cannot answer. You can contact 360Works support in a variety of ways. Our office is open 10am – 6pm ET, and you can reach us at 770-234-9293.

You can also email us at any time at plugins@360works.com.


Helping Us Help You

When we provide support it is important for us to have the most accurate information available. To do so, we may ask you for a few items that may be helpful. If possible, please have this information available when contacting 360Works Support.


Product Information

The version and license of the plug-in you are using, the version of FileMaker Pro or FileMaker Server that you are using, and your operating system.


Plugins10118.png


This shows the License Type (Enterprise License) and Version (1.56). Also notice the “Report a bug” button.


Bug Report

If a plug-in is malfunctioning, a bug report is immensely helpful to identify the problem. To generate a report, logout then log back in to FileMaker. Reproduce the issue and immediately go to FileMaker Pro Preferences > Plug-ins. Select the plug-in, click “Configure” then click “Report a Bug”. This will send a bug directly to our support team who will contact you to follow up.


Getting Log Files

Log files help to tell us what is happening when a plug-in malfunctions. If you are asked to provide a log file, you can do so easily by navigating to the correct location based on your operating system and FileMaker version.


If using FileMaker Pro:

OS X: /Users/userName/Library/Logs/360Plugin Logs/360Plugins_XXXXX.log


Windows XP or S2003: C:\Documents and Settings\<userName>\My Documents\360Plugin Logs\360Plugins_XXXXX.log


Windows Vista, 7, or S2008: C:\Users\<userName>\Documents\360Plugin Logs\360Plugins_XXXXX.log


If Using FileMaker Server:

OSX: /Library/FileMaker Server/Logs/360Plugin Logs/360Plugins_XXXXX.log


Windows XP or S2003: C:\Documents and Settings\Default User\My Documents\360Plugin Logs\360Plugins_XXXXX.log


Vista: C:\Users\Default User\Documents\360Plugin Logs\360Plugins_XXXXX.log

Windows 7, S2008: C:\Program Files\FileMaker\FileMaker Server\Logs\360Plugin_ServerScripting64.log

Personal tools
Namespaces

Variants
Actions
Plug-in Products
Other Products
Navigation
Toolbox