360Works Scribe/Documentation
360Works Scribe User Guide
Scribe is a multi-purpose plugin for reading and manipulating documents, and working with text. See the 'How to use Scribe.fp7' file for step-by-step tutorials.
360Works Plugin Setup Guides
See Plugins_101 for Error reporting, installation, registration, and more.
Function Summary
- ScribeDifferenceReport ( someText ; otherText ) — Returns a report on the types of differences between two blocks of text.
- ScribeDifferencesBetween ( someText ; otherText { ; options } ) — Returns the highlighted differences between two blocks of text.
- ScribeDocAppend ( data ) — Appends data to the end of a document.
- ScribeDocCancel — Closes the currently loaded document without saving any pending changes.
- ScribeDocListFields — Lists all fields in the loaded document.
- ScribeDocLoad ( containerOrUrl { ; password=xxxxx } ) — Loads a file.
- ScribeDocReadValue ( name ) — Reads a field value from the currently loaded file.
- ScribeDocSaveContainer ( newName {; flatten=true } ) — Returns the currently loaded file as a container field, applying any modifications.
- ScribeDocSaveFile ( path {; flatten=true } ) — Saves the currently loaded file to disk, applying any modifications.
- ScribeDocSubstitute ( searchText ; replaceText ) — Replaces all occurrences of
searchTextwithreplaceTextin the currently loaded document. - ScribeDocWriteValue ( name ; value ) — Write a field value in the currently loaded file.
- ScribeFileAsKeywords ( fileOrContainer ) — Returns a unique list of keywords for the
file. - ScribeFileAsText ( fileOrContainer{; param1=value1; param2=value2} ) — Returns the plain text content of the
file. - ScribeHighlight ( text; highlightPattern {; param1=value1 ; param2=value2 ; ...} ) — Highlights all occurrences of
highlightPatternintext. - ScribeLastError — Returns the last Scribe-related error which occurred.
- ScribeLicenseInfo — Returns information about the license used.
- ScribePatternMatchAll ( text; regex {; flags=flag1+flag2+flag3+...} ) — Returns a newline-delimited list containing pattern matches.
- ScribePatternReplaceAll ( text; regex; replacement {; param1=value1 ; param2=value2 ; ...} ) — Replace all occurrences of a regex pattern with some replacement text.
- ScribeRegister ( licenseKey; registeredTo ) — Registers the plugin.
- ScribeSetErrorCapture ( errorCapture ) — Toggles error dialogs on or off.
- ScribeStyleAddedText ( color ; styles { ; open ; close } ) — Sets the style to use for displaying added text.
- ScribeStyleDeletedText ( color ; styles { ; open ; close } ) — Sets the style to use for displaying deleted text.
- ScribeStyleModifiedText ( color ; styles { ; open ; close } ) — Sets the style to use for displaying modified text.
- ScribeVersion — Returns the version of the plugin which is installed.
Function Detail
ScribeDifferenceReport ( someText ; otherText )
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
someText- initial text
otherText- modified text
ScribeDifferencesBetween ( someText ; otherText { ; options } )
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.
someText- intial text
otherText- revised text
options- options
ScribeDocAppend ( data )
Appends data to the end of a document. This is useful if your file template does not contain text to replace, or you want to add a repeating section to a document.
data
ScribeDocCancel
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.
ScribeDocListFields
Lists all fields in the loaded document.
PDF Support
Returns any named acrofields.
Word Support (Office 2007 format or later. Works with .docx files only.)
Returns any named placeholder tags.
Excel Support (Office 2007 format or later. Works with .xlsx files only.)
Returns a list of sheets in the excel document.
ScribeDocLoad ( containerOrUrl { ; password=xxxxx } )
Loads a file. You must load a file before calling any of the other ScribeDoc* functions.
containerOrUrl- container, path (including File URLs), or URL for the file being loaded.
args- optional arguments.
ScribeDocReadValue ( name )
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. Works with .doc and .docx files.)
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.
name- attribute name to read.
ScribeDocSaveContainer ( newName {; flatten=true } )
Returns the currently loaded file as a container field, applying any modifications. This closes the document after saving it to a temporary folder.
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("") ]
ScribeDocSaveFile ( path {; flatten=true } )
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.
ScribeDocSubstitute ( searchText ; replaceText )
Replaces all occurrences of searchText with replaceText in the currently loaded document.
Note that searchText and replaceText 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 files only).
To replace named form fields or cells in a PDF form, Word Document, or other file, use the ScribeDocWriteValue function instead.
Word documents support image replacement in Scribe 2.0, you can pass a container as the replaceValue, and an image will be inserted into your Word document.
To use this, you must first load a document using ScribeDocLoad.
Word (.docx only) 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.
searchString- text to find
replaceValue- text to replace
searchStringwith. Word documents support image replacement as well.
ScribeDocWriteValue ( name ; value )
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. You can also write values to checkboxes and radio buttons. The only values you can write are "Off" or "Yes", and they are case-sensitive.
Word Support
Microsoft Word supports named placeholders in word documents (.docx files only) 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 files 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.
Note:
Due to the nature of writing directly to the document XML, calculations in Excel cells may not fire automatically when the value is written.
name- field / cell to write to
fmValue- data to write
ScribeFileAsKeywords ( fileOrContainer )
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.
file- file or container field to extract index from
ScribeFileAsText ( fileOrContainer{; param1=value1; param2=value2} )
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:
- 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)
file- file or container field to extract text from
ScribeHighlight ( text; highlightPattern {; param1=value1 ; param2=value2 ; ...} )
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"
)
]
text- The input text
highlightPattern- the word or regular expression pattern to highlight
additionalParameters- Additional parameters are specified using a name=value syntax. The parameters
colorRGB,sizeandstylescontrol the look of the replaced text. The parameterflagscontrols the way in which pattern matching is performed.
highlightPattern highlighted with the current styles.
ScribeLastError
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.
"" if there was no error.
ScribeLicenseInfo
Returns information about the license used.
ScribePatternMatchAll ( text; regex {; flags=flag1+flag2+flag3+...} )
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.*"
)
text- input text
regex- regular expression pattern.
flags- An additional parameter used to specify flags that control how pattern matching is performed. To specify multiple flags, separate each with a plus sign (e.g., ..."flags=literal+ignoreWhitespace")
ScribePatternReplaceAll ( text; regex; replacement {; param1=value1 ; param2=value2 ; ...} )
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.
Backreferences can also be used with the regular expression. Replacement text can use dollar sign syntax ($1, $2, etc.) to refer to these groups.
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+" ;
"¶"
)
// 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
text- The input text
regex- The regular expression
replacement- The text to replace the found occurrences with
additionalParameters- Additional parameters are specified using a name=value syntax. The parameters
colorRGB,sizeandstylescontrol the look of the replaced text. The parameterflagscontrols the way in which pattern matching is performed.
regex replaced with replacement
ScribeRegister ( licenseKey; registeredTo )
Registers the plugin.
licenseKey- a valid license key
registeredTo- the company the plugin is registered to
"ERROR" on failure.
ScribeSetErrorCapture ( 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 ScribeSetErrorCapture with a parameter of true. That will suppress the error dialog from appearing to the user.
errorCapture- set to true to suppress the default popups.
ScribeStyleAddedText ( color ; styles { ; open ; close } )
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
color- a FileMaker RGB value (such as 'rgb(255,0,0)' for red) or HTML-style hex value (such as "#FF0000" for red)
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
ScribeStyleDeletedText ( color ; styles { ; open ; close } )
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.
color- a FileMaker RGB value (such as 'rgb(255,0,0)' for red) or HTML-style hex value (such as "#FF0000" for red)
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
ScribeStyleModifiedText ( color ; styles { ; open ; close } )
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.
color- a FileMaker RGB value (such as 'rgb(255,0,0)' for red) or HTML-style hex value (such as "#FF0000" for red)
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
ScribeVersion
Returns the version of the plugin which is installed.