360Works Scribe User Guide

Returns a report on the types of differences between two blocks of text. This will always return three return-separated values: additions, modifications, deletions. Each line consists of a label, edit count, and character count.

For example, the following report:

additions: 2 214
modifications: 0 0
deletions: 1 47

Indicates that:

• 2 blocks were added, for a total of 214 characters
• No modifications
• 1 deletion, of 47 characters

Returns the highlighted differences between two blocks of text. Any text which is in 'otherText' but not in 'someText' is considered an addition, and is styled according to the ScribeStyleAddedText style. Any block of text which has changed from 'someText' to 'otherText' is considered modified text, and is styled according to the ScribeStyleModifiedText style. Any text which is in 'someText' but not in 'otherText' is considered a deletion, and is styled according to the ScribeStyleDeletedText style.

Custom Options

Pass "verbose=true" as a custom option to cause modifications to be displayed as a delete then an insert, instead of a modification.

Closes the currently loaded document without saving any pending changes. This releases any in-memory resources or file locks used by the currently loaded document.

Lists all fields in the loaded document.

PDF Support

Returns any named acrofields.

Word Support (Office 2007 format or later)

Returns any named placeholder tags.

Excel Support (Office 2007 format or later)

Returns a list of sheets in the excel document.

Loads a file. You must load a file before calling any of the other ScribeDoc* functions.

Reads a field value from the currently loaded file. The behavior of this function depends on the type of document currently loaded (see ScribeDocLoad).

PDF Support

To read an acrofield from a PDF, pass the name of the acrofield whose value you wish to retrieve.

To read metadata values, use the respective name parameter:

• PDFTitle - The document's title.
• PDFAuthor - The name of the person who created the document.
• PDFSubject - The Subject of the document.
• PDFKeywords - Keywords associated with the document.
• PDFCreator - The name of the application that created the document.
• PDFProducer - If the document was converted to PDF from another format, the name of the application that converted it to PDF.
• PDFCreationDate - The date and time the document was created, in human-readable form.
• PDFModDate - The date and time the document was most recently modified, in human-readable form.

Note: the descriptions for the fields above are suggested by PDF standards community, but may not strictly represent the values in those fields.

Word Support (Office 2007 format or later)

Microsoft Word supports named placeholders in word documents called Content Control Fields. Pass the tag name of the Content Control Field as the parameter. Content control fields can only be created on Office 2007 on Windows, but can be read and written on both Windows and Mac. More information about how to make content control fields can be found here.

Excel Support (Office 2007 format or later)

To read values from an excel sheet, pass the coordinates of a single cell, e.g. "A5".

To specify a sheet other than the first sheet, include the sheet name followed by an exclamation point, e.g. "Sheet 2!BB42".

XML Support

To read values from an XML document, pass an XPath expression identifying the node to be modified as the first parameter.

Returns the currently loaded file as a container field, applying any modifications. This closes the document after saving it.

The newName parameter tells Scribe what to name the container field value. This can take two forms:

• It can be empty, like this: ScribeDocSaveContainer(""). That tells Scribe to keep the original filename.
• It can be just a filename, like this: ScribeDocSaveContainer("MyNewFile.doc"). That tells Scribe to return a container field with this new filename.

The optional flatten parameter can be used with PDF forms to save a "flattened" version of the form, this would make the form fields unenterable.

For example, if you've done a find and replace operation on a Word document and would like to store it into a container field called 'ResultContainer' while retaining the original filename, you would do it this way:

Set Field[ ResultContainer; ScribeDocSaveContainer("") ]

Saves the currently loaded file to disk, applying any modifications. This closes the document after saving it.

The path parameter tells Scribe where to save the file to. This can take several forms:

• It can be empty, like this: ScribeDocSaveFile(""). That tells Scribe to save the modified file into a temporary directory, keeping the original filename.
• It can be just a filename, like this: ScribeDocSaveFile("MyNewFile.doc"). That tells Scribe to save the modified file into a temporary directory, with a new filename.
• It can be just a directory, like this: ScribeDocSaveFile( Get (DesktopPath) ). That tells Scribe to save the modified file into the specified directory, keeping the original filename.
• It can be a full path with a filename, like this: ScribeDocSaveFile( Get(DesktopPath) & "MyNewFile.doc" ). That tells Scribe to save the modified file into the specified directory with a new filename.

The optional flatten parameter can be used with PDF forms to save a "flattened" version of the form, this would make the form fields unenterable.

Replaces all occurrences of searchString with replaceString in the currently loaded document. Note that searchString and replaceString should generally should be short pieces of text, which only span one line (for convenience... long search strings can be more complicated to correctly enter into FileMaker calculations). This feature is only available for Microsoft Word 2007 and later (docx format). Carriage returns are ignored by this function. To replace named form fields or cells in a PDF form, Word Document, or other file, use the ScribeDocWriteValue function instead.

To use this, you must first load a document using ScribeDocLoad.

Word (.docx) Best Practices

It is recommended for placeholders to be short and use all capital letters. It is also best not to use surrounding characters (%, <, etc.). If modification needs to be made to a placeholder, make sure to highlight the ENTIRE placeholder (%, <, included if you use them) first. This is due to how Word handles strings internally. If only a part of the placeholder string has been typed over, Word will store the string as separate XML blocks and will not be found using ScribeDocReplace.

It is also best practice if you see red or green underlines in the placeholder to fix them prior to attempting to use this function as well.

Saving the File

After calling ScribeDocSubstitute one or more times, save the modified file using ScribeDocSaveFile.

If you need to substitute many different text occurrences, just call this function once for each term that you want to find and replace.

Write a field value in the currently loaded file. The behavior of this function depends on the type of document currently loaded (see ScribeDocLoad).

To use this, you must first load a document using ScribeDocLoad.

PDF Support

To write an acrofield on a PDF, pass the name of the acrofield whose value you wish to set as the first parameter.

Word Support

Microsoft Word supports named placeholders in word documents called Content Control Fields. Pass the tag name of the Content Control Field as the first parameter. Content control fields can only be created on Office 2007 on Windows, but can be read and written on both Windows and Mac. More information about how to make content control fields can be found here.

To do a find/replace operation on text in a word document, use the ScribeDocSubstitute function.

Excel Support

To write values to an excel sheet (.XLSX only), pass the coordinates of a single cell, e.g. "A5" as the first parameter.

To specify a sheet other than the first sheet, include the sheet name followed by an exclamation point, e.g. "Sheet 2!BB42".

Writing a value to a non-exisent sheet will generate an error. If you specify a non-existent cell or row, it will be created.

XML Support

To write values to an XML document, pass an XPath expression identifying the node to be modified as the first parameter.

Saving the File

After calling ScribeDocWriteValue one or more times, save the modified file using ScribeDocSaveFile.

Returns a unique list of keywords for the file. Unlike ScribeFileAsText, this only returns unique names, and strips out common "stop words" like "a", "and", "the", etc. This can reduce storage requirements if you are performing text searches against the contents of files, but don't need the extracted text to be human-readable.

Returns the plain text content of the file.

For binary file document formats such as Word, PDF, etc. this attempts to return a human-readable presentation of the document. XML documents are returned as-is. Any unrecognized file will have its raw text contents returned (see optional parameters to customize this).

You can pass in optional additional parameters to customize the behavior of this function. A list of customizations follows:

• onlyKnownTypes=0 or 1. If this is set to 1, then Scribe will return an empty value "" for unknown file types, instead of returning their raw contents. The default is 0.

Here is a list of supported file types for reading text from:

• pdf
• doc, docx
• xls, xlsx
• ppt, pptx
• xml, xsd
• rtf
• htm, html
• JPEG (will read EXIF metadata)
• csv, txt, tab
• msg (Outlook emails)
• pages, key (Apple's Pages and Keynote documents '08 & '09)

Highlights all occurrences of highlightPattern in text.

Unlike the substitute function, this is case-insensitive by default. The highlightPattern function supports regular expression patterns.

Regular Expression Pattern Processing

Using the flags optional parameter, you may set the following options, each of which influences the way patterns are matched.

caseInsensitive

Enables case-insensitive matching for US-ASCII characters.

multiline

Does not match line-terminating characters. This means that when the input text is a return-separated list, each line is matched independently.

literal

Treats metacharacters like ^ and $ and escape sequences like \t as literals.

includeLineEndings

Matches line-terminating characters, which means that a return-separated list would be treated as a single text block.

ignoreWhitespace

Ignores whitespace characters.

Example

Example of a highlight operation to match the string "file://" at the beginning of each line of a return-separated list.

Set Field [ Globals::highlighted_text =
    ScribeHighlight(
    "file://temp/doc.txt" & ¶ &
    "file://documents/doc.txt" & ¶ &
    "http://my.site.com/home" & ¶ &
    "ftp://my.ftpsite.com/upload" ;
        "^file://" ;
        "flags=multiline"
    )
]

This matches "file://temp/doc.txt" & ¶ & "file://documents/doc.txt"

Style, color and size

Highlighting style is determined by the three optional parameters: colorRGB, styles, and size. Consult the Filemaker TextStyleAdd and TextColor documentation for more details about named Filemaker text styles and colors.

Example

Example of a highlight operation to make any occurrences of "atlanta" blue and bold (the default highlight style is bold, blue text):

Set Field [ Globals::highlighted_text =
    ScribeHighlight(Documents::body ; "atlanta")
]

Example of a highlight operation to highlight runs of 1 or more sequential numbers as green italic text:

Set Field [ Globals::highlighted_text =
    ScribeHighlight(
        Documents::body ;
        "[0-9]+" ;
        "colorRGB=" & RGB(0;255;0) ;
        "styles=" + Italic"
    )
]

Returns the last Scribe-related error which occurred. This should be called any time that a plugin function returns "ERROR" to get a user-readable description of the error.

Returns information about the license used.

Returns a newline-delimited list containing pattern matches. Any text that is not a pattern match will be omitted.

Example of a function to extract a return-separated list of numbers from a string.

ScribePatternMatchAll("123 and 5321 are open, but 0121 is closed" ; "[0-9]+")
/* returns the following:
123
5321
0121
*/

Regular Expression Pattern Processing

Using the flags optional parameter, you may set the following options, each of which influences the way patterns are matched.

caseInsensitive

Enables case-insensitive matching for US-ASCII characters.

multiline

Does not match line-terminating characters. This means that when the input text is a return-separated list, each line is matched independently.

literal

Treats metacharacters like ^ and $ and escape sequences like \t as literals.

includeLineEndings

Matches line-terminating characters, which means that a return-separated list would be treated as a single text block.

ignoreWhitespace

Ignores whitespace characters.

The default behavior of this function uses the caseInsensitive and includeLineEndings flags, so the following function calls are equivalent:

ScribePatternMatchAll(
    "Wilhelm¶wilson¶Williams¶Zander" ;
    "wil.*" ;
    "flags=includeLineEndings+caseInsensitive"
)
ScribePatternMatchAll(
    "Wilhelm¶wilson¶Williams¶Zander" ;
    "wil.*"
)

Replace all occurrences of a regex pattern with some replacement text. The replacement text can optionally be styled.

Highlighting style is determined by the three optional parameters: colorRGB, styles, and size. Consult the Filemaker TextStyleAdd and TextColor documentation for more details about named Filemaker text styles and colors.

Regular Expression Pattern Processing

Using the flags optional parameter, you may set the following options, each of which influences the way patterns are matched.

caseInsensitive

Enables case-insensitive matching for US-ASCII characters.

multiline

Does not match line-terminating characters. This means that when the input text is a return-separated list, each line is matched independently.

literal

Treats metacharacters like ^ and $ and escape sequences like \t as literals.

includeLineEndings

Matches line-terminating characters, which means that a return-separated list would be treated as a single text block.

ignoreWhitespace

Ignores whitespace characters.

Example of simple replace, converting two or more consecutive line breaks to a single line break:

ScribePatternReplaceAll(
    "Line one¶Line Two¶¶¶Line Three¶Line Four" ;
    "\n+" ;
    "\n"
)
// returns "Line one¶Line Two¶Line Three¶Line Four"

Example of a highlighting replace operation, highlighting the literal string "quick" by using styles:

ScribePatternReplaceAll("The quick brown fox" ;
    "quick" ;
    "quick" ;
    "colorRGB=" & RGB(128 ; 128 ; 255) ;
    "styles=" + Bold
)
// returns The quick brown fox

Registers the plugin.

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

This will affect all calls to ScribeDifferencesBetween until you quit FileMaker.

The available styles are:

• Plain
• Bold
• Italic
• Underline
• Condense
• Extend
• Strikethrough
• SmallCaps
• Superscript
• Subscript
• Uppercase
• Lowercase
• Titlecase
• WordUnderline
• DoubleUnderline

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

This will affect all calls to ScribeDifferencesBetween until you quit FileMaker.

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

This will affect all calls to ScribeDifferencesBetween until you quit FileMaker.

Returns the version of the plugin which is installed.