360Works Difference Engine User Guide

The 360 Works DifferencePlugin shows differences between blocks of text as styled text. You can customize the color and style of text which is used to represent added, deleted, or modified text.

Each of the three style customization methods accepts values for red, green, blue, styles, as well as optional values for opening tags and closing tags. The red, green, and blue must be numbers between 0 and 255. The styles number can be any combination of Filemaker style codes, such as: bold + italic + strikethrough. Consult the Filemaker reference for the numeric equivalents for these keywords, if necessary. The opening and closing tags are blocks of text that are appended immediately before or after added, deleted or modified text.

Note: In addition to the standard FileMaker text styles, you can pass a -1 as a style parameter, and text of this type will not be returned in the result. This is especially useful for deletions. If -1 is passed as a style parameter for deletions, three characters of text (excluding leading and trailing whitespace) immediately preceding and immediately following the deletion will be styled as plain red text. In addition, any parameters passed as opening and closing tags will be applied before and after the plain red text.

At times it is difficult to discern between a single large edit and many smaller edits. The difference plugin must find a certain number of matching consecutive characters (15 by default) to consider the characters a match. If fewer than the requisite number of characters occur between differences, they will appear as a single edit block. Future versions of the difference plugin may expose some API for fine-tuning this behavior, but the default typically results in the desired behavior.

Installation

Requirements

FileMaker version 7 or higher.

Java Virtual Machine (JVM) version 1.4.2 or later. If you are running a JVM earlier than 1.4.2, you should upgrade. Download a JVM from http://www.java.com/en/download/. If you are not sure what version of Java you have installed, you can do 'java -version' on the command line in Windows or OS X.

Windows, or Mac OS X version 10.4 or higher.

Note to intel Mac users: running this plugin under Rosetta is not supported. Upgrade to FileMaker 8.5 to run our plugin in native Intel mode.

Install Steps for FileMaker Pro

Drag the plugin from the MAC or WIN folder into your FileMaker extensions, and restart FileMaker. You will need to enter your license key before you can use it. After FileMaker starts up with the plugin installed, open FileMaker preferences, click on the Plug-ins tab, select the plugin from the list, and click the Configure button. Enter your license key and company name in this dialog. You will only need to do this once on a given machine. Alternately, you can use the registration function to register the plugin during a startup script.

This will also enable the plugin for use with Instant Web Publishing from the FileMaker Pro client software.

If the plugin does not load correctly, double-check that you meet the system requirements.

Install steps for FileMaker Web Publishing Engine / Instant Web Publishing

You do not need to do this step unless you plan on using the plugin with Instant Web Publishing or Custom Web Publishing with FileMaker Server Advanced. You will need an Enterprise License to use this feature.

For installing into the Web Publishing Engine with FileMaker 9 Server or FileMaker Server Advanced, drag the plugin from the MAC or WIN folder into the FileMaker Server/Web Publishing/publishing-engine/wpc/Plugins folder. If there is no 'Plugins' folder inside the 'wpc' folder, then create it manually. Restart FileMaker Web Publishing, and now the plugins should be ready to go.

Note that you must use the registration function to register the plugin, since there is no preferences dialog in the FileMaker Web Publishing Engine to enter the license key and company name.

Note that due to a bug which we and other plugin vendors have reported to FileMaker, web plugins do not work in FileMaker Web Publishing Engine 8.0v4 on Mac OS X. You will need to use a later version, like 9, or an earlier version, like 8.0v3. The Windows FileMaker Server 8.0v4 does not have this bug, and will work correctly.

The easiest way to test whether the plugin is working is to have a calculation which calls the version function of the plugin, and display that on an IWP layout. If it shows "?", then the plugin is not working. If it shows a number, then the plugin has been installed successfully.

Install steps for FileMaker Server 9

You do not need to do this step unless you plan on using the plugin with scheduled script triggering, a new feature in FileMaker Server 9. You will need an Enterprise License to use this feature.

  1. Drag the plugin from the MAC or WIN folder into the FileMaker Server/Database Server/Extensions folder (Server 8 and older versions of server use the path FileMaker Server/Extensions/Plugins).
  2. Restart FileMaker Server. In the Server Admin application, go to Configuration -> Database Server->Server Plug-ins.
  3. Check the box that says 'Enable FileMaker Server to use plug-ins', and then check the 'enabled' box for this plugin. You should now be able to write schedules that trigger scripts which use the plugin.

Note that you must use the registration function to register the plugin, since there is no preferences dialog in FileMaker Server to enter the license key and company name.

Feedback

We love to hear your suggestions for improving our products! If you are experiencing problems with this plugin, or have a feature request, or are happy with it, we'd appreciate hearing about it. Send us a message on our website, or email us!

Function Summary

Function Detail

differencesBetween ( someText ; otherText { ; options } )

// * Returns the highlighted differences between two Strings. // * Any text which is in 'otherText' but not in 'someText' is considered an addition, and is styled according to the diffStyleAddedText style. // * Any block of text which has changed from 'someText' to 'otherText' is considered modified text, and is styled according to the diffStyleModifiedText style. // * Any text which is in 'someText' but not in 'otherText' is considered a deletion, and is styled according to the diffStyleDeletedText style. // *

// *

Custom Options

// * Pass "verbose" as a custom option to cause modifications to be displayed as a delete then an insert, instead of a modification. // * @param someText intial text // * @param otherText revised text // * @param options options // * @return Styled text which displays the differences between the two strings, according to highlighting parameters. //

diffLastError

Returns defailed 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 null if there was no error.

diffRegister ( licenseKey ; registeredTo )

Registers the Plugin.

Parameters:
licenseKey - a valid license key string, or the literal string "DEMO" to run in demo mode.
registeredTo - the company name for the license key used.
Returns: 1 on success, or "ERROR" on failure.

diffStyleAddedText ( red ; green ; blue ; styles { ; open ; close } )

Sets the style to use for displaying added text. The default plugin behavior is to display added text as green.

Parameters:
red - a Number from 0-255
green - a Number from 0-255
blue - a Number from 0-255
styles - Any of the Filemaker style keywords, or -1 to hide text of this type in the diff result.
open - An optional text string appended before an addition
close - An optional text string appended after an addition
Returns: 1 on success, or "ERROR" on failure. Use diffLastError to get more information on the error.

diffStyleDeletedText ( red ; green ; blue ; styles { ; open ; close } )

Sets the style to use for displaying modified text. The default plugin behavior is to display modified text as blue.

Parameters:
red - a Number from 0-255
green - a Number from 0-255
blue - a Number from 0-255
styles - Any of the Filemaker style keywords, or -1 to hide text of this type in the diff result.
open - An optional text string appended before a deletion
close - An optional text string appended after a deletion
Returns: 1 on success, or "ERROR" on failur. Use diffLastError to get more information on the error.

diffStyleModifiedText ( red ; green ; blue ; styles { ; open ; close } )

Sets the style to use for displaying deleted text. The default plugin behavior is to display deleted text as red.

Parameters:
red - a Number from 0-255
green - a Number from 0-255
blue - a Number from 0-255
styles - Any of the Filemaker style keywords, or -1 to hide text of this type in the diff result.
open - An optional text string appended before a modification
close - An optional text string appended after a modification
Returns: 1 on success, or "ERROR" on failur. Use diffLastError to get more information on the error.