The Scripter's Scrapbook API

An API (or Application Programming Interface) allows one program to control another by using supplied commands. The Scripter's Scrapbook API supports all the commands and functionalities shown in the index on both Windows and Macintosh operating systems.

There are two basic kinds of command: Those that 'get' information, and those that 'set' information or action something. Using a combination of these within your own scripts you can tell the Scripter's Scrapbook to supply information, perform tasks, and so build your own plugin and external script utilities that do what you want by 'scripting the Scrapbook'.

Option 1: Using Text files
If you wish to use the API from within your own programming environment, use text scripts and IAC to communicate with your Scrapbook. A full guide to the language is beyond the scope of this handbook but you will find the language very easy to pick up. There are some tips in "Using the IAC" and you can use the ScriptMaker to test whether your script will compile.

Option 2: Using PlugIn stacks
If you wish to write Revolution stack plugins, the only thing you have to learn is what commands are available and what they can do for you. To access your plugIn, place it in the 'ssBk PlugIns' folder and select it from the Tools:PlugIns menu.

And that's what this handbook does... Every command has a syntax description, a full explanation, and at least one example. It also provides you with interactive 'trial and error' syntax tests for each one. Then, when you feel comfortable, use the ScriptMaker to test your own scripts.

All you need is an open copy of the Scripter's Scrapbook that supports the API (ssBk version 5.2 or later) because that's where the API commands are stored.

If you meet something that needs a new command, let us know and we'll put it on the To-Do list.

IAC (Inter-Application Communications) is when you want to use the API commands from another program such as Visual Basic, Flash or Director. The Scrapbook IAC uses text files. This means it is compatible with and transferable across (or even between) all supported platforms and operating systems, for all software development programs and all languages, and for all Scrapbooks whether runnung as a standalone application or as a Revolution plugin utility.

Step 1:
Your own program writes a script as a text file to the 'IACin' folder or you can drop a script in a text file into the folder yourself. Only ONE script file should be written or dropped at a time. If more than one script file is available, the API will attempt to execute them in alphabetical order by file name with perhaps unexpected results.

Step 2:
The Scrapbook reads the script in your file, either moves your file to the'oldScripts' subfolder or deletes it depending on the Scrapbook Prefs, and finally executes the script you provided.

Step 3:
Optionally, data can be written to the 'IACout' folder at any time in your script by using the ssBkIACwrite command. Your program can collect it, or you can open it yourself, or you can use the ssBkIACpeek command to read the data.

These folders are automatically created when required. The path for each defaults to the same folder as the current Scrapbook. The paths can be obtained with the ssBkIACgetReadDir and ssBkIACgetWriteDir commands.

IAC scripts should be written as ASCII text files either using the built-in ScriptMaker, or NotePad (PC), SimpleText (Mac) or TextEdit in plain mode (OS X) for example, or generated on-the-fly by your own development software. Text coloring in the examples below is for explanation clarity only. The script language is Revolution (see www.runrev.com) but the Revolution IDE is not required to use the ssBk API... If your Scrapbook is open, you can use the ssBk API in your IAC scripts.

Note
Only one script can be included in an IAC file. If you need to apply sequential scripts, use the ssBkIACwrite command to establish when a script has finished before writing another file. You may find it better to use variables and conditional statements in the one script, but the choice is yours.

Note
Comments in your script can be prefixed either with a # character or with a --

1. 'The Result'
This term contains the output of the previous command. It can be empty or contain an error or contain the requested information.

  ssBkGetIndexEntries
  put the result into tResult
  ssBkIACwrite tResult,"entryList.txt"

2. Variables
You can include temporary variables like this (they do not have to be declared first)...

  ssBkGetIndexEntries
  put the result into tOutput # tOutput is the variable
  ssBkAnswerList tOutput
  ssBkIACwrite the result,"selection.txt"

  ssBkGetIndexEntries
  ssBkAnswerList the result,"single"
  put the result into tSelectedEntry
  if "ERR:" is word 1 of tSelectedEntry then
    -- Unlikely, but for demonstration purposes
    ssBkAnswer "warn","Error","An error occured.","OK"
    ssBkExitScript
  else if tSelectedEntry = "Cancel" then
    ssBkExitScript
  else
    ssBkGetEntryData tSelectedEntry,"Content"
    put the result into tData
  end if
  ssBkIACwrite tData,"selectedCode.txt"

Getting 'The Result'
This is where the command places the output of the command for you to retrieve. 'The result' can be empty, data or an error message.

1. If the script cannot be run due to syntax errors, you will get a 'Parsing Error' warning.

2. If there is a problem interpreting a script line, the script will exit at that point with an 'Execution Error' warning.

3. If the API command itself encounters a problem, 'the result' will always start with "ERR:" but you can supress the Script Command Error dialog (see the ssBkAPIerrorDialog command).

Don't miss the result
Grab 'the result' immediately after the command. For example...

  ssBkGoEntry "My Entry"
  put the result into tResult
  if tResult is not empty then ssBkAnswer tResult

ssBkGoEntry "Mmy Entry typo"
if the result is not empty then ssBkAnswer the result

because the second 'result' will have overwritten the first due to the "if" statement.

Checking for an Error
Both the following check for an error, but the second is more robust...

  ssBkImportFile pFilePath
  put the result into tOutput
  if "ERR:" is in tOutput then ...
  else ...

  ssBkImportFile pFilePath
  put the result into tOutput
  if word 1 of tOutput is "ERR:" then ...
  else ...

Generating a return-separated list
Several API commands can take a return-separated list for multiple values. If the result of a command is already a return-separated list, you can use 'the result'...

To build a return-separated list yourself, either use CR to indicate a line break...

The 'format' syntax is the same as the C language printf function and requires parenthases with the value in quotes and \n indicating a new line.

Script line Continuation
The \ character can be used to split a line and make it more readable, for example...

put "Are you sure you want to delete all Entries? You " & \
"cannot undo this and you should check if you have " & \
"a backup first." into tStr
ssBkAnswer "warn","Delete All",tStr,"Cancel","OK"

1. General
A plugin can most easily be developed using Revolution. This is not to say that you cannot write a plugin in another language but you will need to use IAC implementation. The following refers to Revolution plugins; if you are writing a plugin in another language, please refer to Using the IAC section in this handbook.

2. Naming Compliance
Plugins that begin 'ssbk' are automatically terminated when a Scrapbook closes. Call your plugin 'ssBk Name' with a SPACE after ssbk to ensure it complies with this and is not mis-interpreted as one of the core plugins that have NO SPACE (such as 'ssBkLibURL' or 'ssBkTokens'). Core plugins do not appear in the Tools menu.

3. Plugins with IAC
There is nothing to prevent a Revolution plugin from using IAC and/or the IAC commands, but direct calls on the API may be more responsive and will not depend on the IAC being active (remember that users can disable IAC in their preferences and there is no command available to over-ride this choice).

4. Testing API availability
Your plugin should test whether the API is available. A simple handler could be...

on mouseUp
if ssbkAPIavailable() then ... -- API is available
else ... -- API is not available
end mouseUp

function ssbkAPIavailable
  try
    ssBkGetVersion
  catch err
    return "false"
  end try
  return "true"
end ssbkAPIavailable

5. Samples
Sample unlocked plugin stacks are available. Review these if you wish; they range from the very basic requiring minimal programming experience to the more advanced.

How many script lines can I write?
There are no limits for scripts implemented in Revolution. If you are using one of the Scripter's Scrapbook runtime applications, scripts are limited to 10 runtime statements in both IAC text files and in the ScriptMaker. If your script is too long, try these options...

Option 1: Efficient scripts
Can you reduce the number of statements by making your script more efficient?

This uses 11 statements...
ssBkGetEntryName "Current"
put the result into tEntryName
put "MyFile.txt" into tFileOut
ssBkIACgetOutDir
put the result into tFolder
ssBkGetEntryData tEntryName, "content"
put the result into tData
open file (tFolder & tFileOut) for append
write tData to file (tFolder & tFileOut)
close file (tFolder & tFileOut)
ssBkAnswer "All done"

This does the same thing in 4 statements...
ssBkGetEntryName "Current"
ssBkGetEntryData the result, "content"
ssBkIACwrite the result,"myFile.txt"
ssBkAnswer "All done"

Option 2: Use plugins
If your script cannot be reduced, the script must be implemented using a plugin written in Revolution (see www.runrev.com). Place the plugin in the 'ssBk plugins' folder, then select it from the PLUGINS menu.

1. Parsing error (the ship doesn't even sail)
This sort of error stops the script from running at all. It occurs when a script cannot compile because is syntactically unsound, for example a missing 'end if'. A "Script Parsing Error" dialog is displayed showing the problem.

2. Execution error (the ship sails, then sinks)
This sort of error will automatically exit the script at the point of error. It occurs when the script is syntactically sound but there is an error in executing a specific script line, for example a typo such as ssBkGgoEntry. Commands up to that point will be executed. A "Script Execution Error" dialog is displayed showing the problem.

3. Script Command error (lifeboats may or may not be available)
This sort of error does not automatically exit your script. It occurs when an API command returns an error in 'the result', for example trying to open a non-existant file. It may or may not be intercepted either automatically by the API (depending on whether the ssBkAPIerrorDialog is 'true' or 'false'), or by your script (depending on whether the script is trapping "ERR:" in the result).

The safest is to always check whether "ERR:" is in 'the result' before continuing...
e.g. if word 1 of the result is "ERR:" then ssBkExitScript

Unless you are sure the script will run error-free, it is probably best to leave ssBkAPIerrorDialog as "TRUE" so the user has the option to cancel if a script command error occurs. Remember, however, that the user can also choose to CONTINUE, and your script should still trap any error that is returned in 'the result' even if it is simply ssBkExitScript.

There may also be occasions when you definately do not want the user to decide, when your script makes the decisions. In this case, ssBkAPIerrorDialog should be false to avoid the buffer option.

The ssBkIACwrite command is available if you wish to save 'the result' or indeed anything else to a file. See also ssBkIACgetOutDir.

Use the ssBk API ScriptMaker to check (and optionally execute) your scripts. It includes an index of all API commands with reference notes.

If a script returns a command error in 'the result' (for example trying to import a
non-existant file), the ssBkAPIerrorDialog setting determines whether a Script
Command Error dialog with CANCEL/CONTINUE intercepts the returned result as
a buffer between the script and the end user.

The setting is global and stays in force until changed.
The setting defaults to TRUE when a Scrapbook opens.

Using
Apply the parameter to display or not display the command error dialog...
"TRUE" - The dialog is displayed first ("Cancel" immediately terminates the script;
"Continue" will return the error details in "the result").
"FALSE" - The error details are immediately returned in "the result".

The Result
'The Result' will be empty if successful, or the current setting, or an error.

Error handling
Errors will be in 'the result': Line 1 is "ERR: <error>", line 2 is the command, line 3
is the offending value.
If the parameter is not recognised, "ERR: Expected true, false or get" will be
returned.

EXAMPLES
The following demonstrates what happens when a command error is encountered...

ssBkAPIerrorDialog "true"
ssBkGoEntry "Mmy Entry typo" # Dialog is presented
put the result into tResult
ssBkAnswer tResult

ssBkAPIerrorDialog "false"
ssBkGoEntry "Mmy Entry typo" # Dialog is not presented
put the result into tResult
ssBkAnswer tResult

Retrieves the current Scrapbook version and the release date. With no qualifier the
date is in seconds, counting from Thursday, January 1, 1970 12:00 AM.

Using
If you specify "L[ongDate]" or "S[hortDate]" it will be formatted according to your
computer's system preferences. Finally, "D[ateItems]" will return the form year,
month, day, hour, minute, second, dayNumber (Sunday=1), or "A[bbrevDate]"
(See also ssBkGetEntryData).

The Result
'The Result' is in two lines: line 1 is the current version and line 2 is the
date. Useful to establish whether the current Scrapbook supports an API command
or the API at all.

EXAMPLE 1
This gets the version information of the current Scrapbook and returns the version
number and date...

ssBkGetVersion "shortDate"
put the result into tResult
put line 1 of tResult into tVers
put line 2 of tResult into tDate
ssBkAnswer "This is v." & tVers && "dated" && tDate

EXAMPLE 2
Not IAC, but a plugin utility handler to make sure the current Scrapbook supports
the API keywords...

if NOT APIavailable() then
  ssBkAnswer "This feature is not supported."&CR&\
    "You need Scripter's Scrapbook v5.2 or later."
  ssBkExitScript
end if

function APIavailable
  try
    ssBkGetVersion
  catch err
    return "false"
  end try
  return "true"
end APIavailable

Navigates to the Entry in the current Scrapbook as specified by <EntryName> or
by keyword.

Using
"Next, "Prev", "First" and "Last" refer to the displayed Entries in the Index.

ssBkGoEntry "My Entry"
put the result into tResult
if word 1 of tResult is "ERR:" then
ssBkAnswer tResult
ssBkExitScript
else .../...

Using
<ContextType> is one of the following...
- "Platforms" retrieves the complete list of available platforms
- "Languages" retrieves the complete list of available languages
- "Categories" retrieves the complete list of available classification categories

The Result
'The Result' is is either an error message or a return-delimited list.

Error handling
Errors will be in 'the result': Line 1 is "ERR: <error>", line 2 is the command, line 3
is the offending value.
If ContextType is not recognized, "ERR: No such ContextType" will be returned.

EXAMPLE 1
This gets the currently defined Categories...

Using
<ToolName/s> is a return-separated list of one or more of "Toolbar", "Select",
"Context", "Attachments", "Categories", "Languages", "PlugIns", "Format" or the
name of a supplied plugin (such as "ssBkChat") or a user plugin. Use ssBkGetPlugIns
for a list of all the currently available ToolNames.

Error handling
Errors will be in 'the result': Line 1 is "ERR: <error>", line 2 is the command, line 3
is the offending value.
If <ToolName> cannot be found, an ssBkLaunchURL error is returned in the result.

EXAMPLE
This opens the text Format, Categories and Context tools along with the Chat...

Using
<Type> can be "All" for a complete list, or "User" or "ssBk". If not supplied, it
defaults to "All".

Error handling
Errors will be in 'the result': Line 1 is "ERR: <error>", line 2 is the command, line 3
is the offending value.
If <Type> is not recognized, "ERR: No such Keyword" is returned in the result.

ssBkGetPlugins "All"
ssBkAnswerList the result,"multiple"
put the result into tResult
if tResult is "Cancel" then ssBkExitScript
else if word 1 of tResult is "ERR:" then ssBkAnswer tResult
else ssBkOpenTools tResult

Using
<keyword> is any one of "Current", "next", "prev", "fwd", "back", "first" or "last".

The Result
The returned value is either an error message, or the name of the specified Entry, or
empty if keyword cannot be evaluated (for example there is no "next" Entry in the
index).

Error handling
Errors will be in 'the result': Line 1 is "ERR: <error>", line 2 is the command, line 3
is the offending value.
If the keyword is not recognised, "ERR: No such Keyword" is returned

No parameters. Returns the number of currently selected Entries in 'the result'.

Retrieves a list of Entries in the current Scrapbook, optionally filtered by the specified
platform/s, language/s, category/s and status type/s.

Using
If no parameters are passed, or if all four parameters are empty, then the entire
index is provided in 'the result'. Otherwise it will provide a filtered list of Entries that
matches ALL the specified criteria. More than one platform, language, category and
status can be supplied, each as a return-delimited list, one per line.

<Platform/s> can be determined from ssBkGetContextList "platforms".
<Language/s> can be determined from ssBkGetContextList "languages".
<Category/s> can be determined from ssBkGetContextList "categories". The more
of a category name that is supplied, the closer the match will be.
<StatusType/s> can be any or all of "Bookmarked", "Protected", "Attached" or
"Selected".

The Result
'The Result' is a return-separated list of Entry names.

EXAMPLE 1
This retrieves all Entries that are Bookmarked...

ssBkGetIndexEntries "","","","Bookmarked"
ssBkAnswer "","Matching Entries",the result,"OK"

EXAMPLE 2
This retrieves all Entries that match OSX for "Rev" that are classified with
"Environment" in the category...

ssBkGetIndexEntries "OSX","Rev","Environment",""
ssBkAnswer "","Matching Entries",the result,"OK"

EXAMPLE 3
This retrieves all Entries that match Windows for "VB" and "Rev" that are classified
with "Environment : Windows", as well as being both Bookmarked and Protected...

ssBkGetIndexEntries "WinOS","VB" &CR& "Rev","Environment : Windows","Bookmarked" &CR& "Protected"
ssBkAnswer "","Matching Entries",the result,"OK"

EXAMPLE 4
This retrieves all Entries that apply to both OSX and Windows, that are applicable to
"Rev", "HTM" and "PERL", and that are classified with both "Maths : Dates" and
"Arrays"...

put "OSX" &CR& "WinOS" into pPlats # Line list
put "Rev" &CR& "HTM" &CR& "PERL" into pLangs # Line list
put "Maths : Dates" &CR& "Arrays" into pCats # Line list
ssBkGetIndexEntries pPlats,pLangs,pCats,""
ssBkAnswer "","Matching Entries",the result,"OK"

EXAMPLE 5
This retrieves all Entries, displays a selectable list, and finally displays the user's
selection...

ssBkGetIndexEntries
ssBkAnswerList the result,"Multiple"
ssBkAnswer "info","You selected...",it,"OK"

ssBkGetIndexEntries "","","","Bookmarked"
put the result into tList
if tList <>"" then
  ssBkShowIndexEntries tList
  ssBkGetIndexCount
  put the result into n
  ssBkAnswer "251003","Bookmarked Entries","There are" &&n&& "Bookmarked Entries.","OK"
else ssBkAnswer "251003","Bookmarked Entries","Sorry, there are no Bookmarked Entries.","OK","",""

ssBkGetIndexEntries "","","","Protected"
put the result into tList
if tList <> "" then ssBkShowIndexEntries tList
else ssBkAnswer "251003","Protected Entries","Sorry, there are no Protected Entries.","OK"

ssBkGetIndexEntries
ssBkShowIndexEntries the result
put the result into n
ssBkAnswer "251003","All Entries","There are"&& n&& "Entries displayed.","OK"

ssBkShowIndexEntries
ssBkAnswerList the result,"Multiple"
put the result into tResult
if tResult is "Cancel" then
  ssBkAnswer "","","You cancelled!","OK"
else
  ssBkShowIndexEntries tResult
  ssBkGetIndexCount
  ssBkAnswer "251003","",the result &&"Entries displayed.","OK"
end if

Retrieves the data from the entry <EntryName>. Embedded source images are not
supported.

Using
<EntryName> evaluates to any valid Entry name.
<Datum> can be "all", "platforms", "languages", "categories", "createDate",
"modifiedDate", "summary", "content", or "source".
Note that "all" is returned preformated; others are returned as data only.
Note that createDate and modifiedDate are returned in seconds, counting
from Thursday, January 1, 1970 12:00:00 AM, unless you additionally specify
"S[hortDate]", "L[ongDate]", "D[ateItems]" or "A[bbrevDate]" as the second
word of the parameter in which case the date will be formatted according to
your computer's system preferences (see also ssBkGetVersion).
e.g. ssBkGetEntryData "MyEntry","CreateDate S".
["HTML"] The third parameter is optional. If passed as "HTML", the data will be
returned HTML-formatted.

EXAMPLE 1
This retrieves the Code portion of an Entry called "My Entry" in html...

ssBkGetEntryData "My Entry","Code","HTML"

EXAMPLE 2
This retrieves the Description portion of an Entry called "My Entry" in plain text...

ssBkGetEntryData "My Entry","Description"

EXAMPLE 3
This retrieves the Modification Date of an Entry called "My Entry" and converts it to
a readable date...

ssBkGetEntryData "My Entry","ModifiedDate L"
ssBkAnswer "","",the result,"OK"

Using
<EntryName> evaluates to any valid Entry name.
<Datum> can be "platforms", "languages", "categories", "description" (top field),
"code" (bottom field), or "source" (source field).
<Value> is the contents for the Datum.

If "HTML" is provided for Description, Code or Source, it means the data in <value>
is HTML-formatted and should be interpreted as such.

Multiple platforms, languages and categories can be supplied...
<Platforms> and <Languages> must be supplied as comma-delimited lists.
<Categories> must be supplied as a return-delimited list, one per line.

If a Platform is provided that does not exist, it is ignored. Use ssBkGetContextList
"Platforms" for a list of existing values.

If a Language is provided that does not exist, it is ignored. Use ssBkGetContextList
"Languages" for a list of existing values.

If a Category is provided that does not exist, it is ignored. Use ssBkGetContextList
"Categories" for a list of existing values.

Error handling
Errors will be in 'the result': Line 1 is "ERR: <error>", line 2 is the command, line 3
is the offending value.
If EntryName does not exist, "ERR: No such Entry" will be returned.
If Datum item is not recognized, "ERR: No such Context" will be returned
If "HTML" is provided for Platforms, Languages or Categories, if will either produce
unexpected results or, if detected, return an error "ERR: HTML not supported".

EXAMPLE 1
This would set the platforms for an Entry called "My Entry" to show Mac OSX and
Windows icons...

EXAMPLE 2
This would set the Description for an Entry called "My Entry" to show "This is a test"...

ssBkSetEntryData "MyEntry","Description","This is a test"

EXAMPLE 3
This would set the Description for an Entry called "My Entry" to show "This is a test"
using html...

Creates a new Entry with the name <EntryName> with or without a promt to
set the Context Options. Once the Entry has been created, you can use
ssBkSetEntryData to set the values of the entry, or include "askContext" and
allow the User to set the options.

Using
<EntryName> evaluates to any Entry name that is not already in use.
[,"AskContext"] is an optional string. If included, the Context Options palette is
displayed for the User. If omitted, the Context Options palette is not displayed.
Both over-ride the default behaviour of the Scrapbook.

Error handling
Errors will be in 'the result': Line 1 is "ERR: <error>", line 2 is the command, line 3
is the offending value.
If <EntryName> is empty, "ERR: Missing Name" will be returned.
If <EntryName> already exists, "ERR: Entry already exists" will be returned.
If <EntryName> is a reserved word, "ERR: Reserved word" will be returned.
(Reserved words are Back, Fwd, Next, Prev, First, Last, Current)
If "AskContext" is not recognized, "ERR: No such keyword" will be returned.

EXAMPLE
This creates a new Entry called "My New Entry"...

ssBkCreateEntry "My New Entry"
put the result into tResult
if tResult is not empty then ssBkAnswer tResult

Using
<CurrentEntryName> evaluates to any valid Entry name.
<NewEntryName> evaluates to an Entry name that is not already in use.

Error handling
Errors will be in 'the result': Line 1 is "ERR: <error>", line 2 is the command, line 3
is the offending value.
If <CurrentEntryName> or <NewEntryName> is empty, "ERR: Missing Name" will
be returned.
If <CurrentEntryName> does not exist, "ERR: No such Entry" will be returned.
If <NewEntryName> already exists, "ERR: Entry already exists" will be returned.
If <NewEntryName> is a reserved word, "ERR: Reserved word" will be returned.
Reserved words are Back, Fwd, Next, Prev, First, Last, Current.

EXAMPLE
This renames an existing Entry called "My Old Entry" as "My New Entry"...

ssBkRenameEntry "My Old Entry","My New Entry"
put the result into tResult
if tResult is not empty then ssBkAnswer tResult

The Result
If <pDialog> is not supplied, the result will be empty if successful or contain an error
message. If <Dialog> is supplied, the parameter is presented in an "OK/Cancel"
warning dialog with "OK" or "Cancel" or an error message in the result.

ssBkDeleteEntry "My Entry"
if "ERR: No such Entry" is in the result then
ssBkAnswer "Can't find that Entry"
end if

EXAMPLE 2
This deletes an Entry called "My Entry" with a confirmation dialog...

ssBkDeleteEntry "My Entry","Are you sure?"
if "ERR: No such Entry" is in the result then
ssBkAnswer "Can't find that Entry"
else if the result is "Cancel"
then ssBkAnswer "You cancelled!"

EXAMPLE 3
This checks for attachments first, then deletes an Entry called "My Entry" either with
or without a warning...

# Check for Attachments...
ssBkGetAttachments "MyEntry"
put the result into tResult
if "ERR:" is word 1 of tResult then
  ssBkAnswer tResult # Probably an unknown EntryName
else
  if tResult is not empty then
    # List of Attachments is returned, so...
    ssBkDeleteEntry "MyEntry","Are you sure? You have Attachments!"
    if the result = "Cancel" then ssBkExitScript
  end if
  ssBkDeleteEntry "MyEntry"
end if

ssBkOmitEntry "My Entry"
if "ERR: No such Entry" is in the result then
ssBkAnswer "Can't find that Entry"
end if

No parameters. Displays the Export dialog as a modal (the script is blocked
until 'the Result' is returned).

The Result
'The Result' is either "Cancel", or a four-line result...
  Line 1 shows the chosen format:
    - html, txt, xml, csv Windows, csv Macintosh or ssbf
  Line 2 shows the chosen Entries:
    - All or Selected or Current
  Line 3 shows the chosen field/s:
    - EntryName, Deployment, Summary, Info, Source
  Line 4 shows the saved file path

Error handling
If an error is encountered, notification is automatic and the script terminates.

EXAMPLE
This exports the required Entries in the required format and reports the result...

ssBkAskExport
put the result into tResult
if tResult is "Cancel" then
  ssBkAnswer "You cancelled."
else
  put line 1 of tResult into tFormat
  put line 2 of tResult into tSelected
  put line 3 of tResult into tData
  put line 4 of tResult into tFilePath
  ssBkAnswer "Entries were successfully exported..."&CR&CR&\
      "1. Entries :" && tSelected &CR&\
      "2. Format :"&& tFormat &CR&\
      "3. Data :" && tData &CR&\
      "4. File path :" && tFilePath
end if

Using
<FilePath/s> is optional. If supplied, it is a return-delimited list of valid file paths.
If <FilePath/s> is not supplied, the user is asked to select a file.

The Result
'The Result' is either "Cancel", or an error message, or the number of files
successfully imported.

Error handling
Errors will be in 'the result': Line 1 is "ERR: <error>", line 2 is the command, line 3
is the number of files imported followed by the names of the files that were skipped.
All filePaths are pre-checked before import starts.
If a specified file does not exist, "ERR: No such File" will be returned with the name
of the missing file in line 3.
If a file cannot be imported, "ERR: Import Error" will be returned with the number
imported in line 3 followed by the names of the files that were skipped.

EXAMPLE
This converts a file called "ReadMe.html" to an Entry...

ssBkImportFile "C:/General Documents/ReadMe.html"
put the result into tResult
if tResult="Cancel" then
ssBkAnswer "You cancelled."
else if "ERR: No such File" is line 1 of tResult then
ssBkAnswer "Can't find" && line 3 of tResult
else ssBkAnswer "All files converted to Entries."

Using
<FilePaths> is optional. If supplied, it is a valid file path to a Scrapbook backup file.
If not supplied, the user is asked to select a backup.

The Result
'The Result' is either an error, "Cancel", or a four-line result...
  Line 1 shows the number of Entries created
  Line 2 shows the number of Entries overwritten
  Line 3 shows the number of Entries skipped
  Line 4 shows the number of attachments

Error handling
Errors will be in 'the result': Line 1 is "ERR: <error>", line 2 is the command, line 3
is the offending value.
If a specified file does not exist, "ERR: No such File" will be returned.
If the file is not a backup file, "ERR: Not a Backup File" will be returned.
If an unexpected error occurs, "ERR: Unexpected Error" will be returned.

ssBkImportBackup
put the result into tResult
if tResult ="Cancel" then ssbkExitScript
else if "ERR:" is in tResult then ssbkAnswer tResult
else ssBkAnswer "Created:" && line 1 of tResult &CR&\
    "Overwritten:" && line 2 of tResult &CR&\
    "Skipped:" && line 3 of tResult &CR&\
    "Attachents:" && line 4 of tResult

Retrieves the names of any attached files for the Entry. Useful as a test before using
ssBkDeleteEntry.

The Result
'The Result' is either a return-separated list of attachments, or an error.

ssBkGetAttachments "My Entry"
put the result into tList
if tList is not empty then
ssBkAnswer tResult
else ssBkAnswer "This Entry has no attachments."

Using
<EntryName> is the name of an existing Scrapbook Entry.
<FilePath> is the long name of a valid file.

Use ssBkGetAttachments to check if the attachment already exists and should
be overwritten. ssBkSetAttachments will overwrite without warning.

If FilePath is not specified, the user is asked to select a file (in which case the filepath
or "Cancel" is in 'the result').

If FilePath is specified, the result will be empty if successful or an error message.

Error handling
Errors will be in 'the result': Line 1 is "ERR: <error>", line 2 is the command, line 3
is the offending value.
  If the Entry does not exist, "ERR: No such Entry" will be returned.
  If the FilePath does not exist, "ERR: No such File" will be returned.
  If any error occurs in the process, "ERR: Unexpected Error" will be returned.

answer file "Select a file..."
put the result into tResult
if tResult="Cancel" then ssBkExitScript
ssBkSetAttachments "MyEntry",tResult
put the result into tResult
else if "ERR:" is word 1 of tResult then
ssBkAnswer tResult
end if

ssBkSetAttachments "MyEntry","C:/MyDocs/myDoc.doc"
put the result into tResult
else if "ERR:" is word 1 of tResult then
ssBkAnswer tResult
end if

Copies the specified Entry attachment and saves it as a file. If <Destination> is
supplied it must evaluate to a valid filePath, otherwise the user is asked where to
save the attachment.

The attachment is not deleted from the Entry after being restored; use
ssBkDeleteAttachments to do this.

Using
  <EntryName> is the name of an existing Scrapbook Entry.
  <AttachmentName> is the name of a valid attachment.
  <Destination> is a valid destination filePath.

Error handling
Errors will be in 'the result': Line 1 is "ERR: <error>", line 2 is the command, line 3
is the offending value.
  If the Entry does not exist, "ERR: No such Entry" will be returned.
  If the Attachment does not exist, "ERR: No such Attachment" will be returned.
  If any error occurs in the process, "ERR: Unexpected Error" will be returned.

ssBkGetAttachments "My Entry" # Gets a list
put the result into tResult
if tResult is empty then
  ssBkAnswer "warn","","There are no attachments","OK"
else
  ssBkAnswerList tResult,"single" # User selects
  put the result into userAnswer
  if userAnswer is "Cancel" then ssBkExitScipt
  ssBkRestoreAttachments "My Entry",userAnswer
  put the result into tOutcome
  if tOutcome is "Cancel" then ssBkExitScipt
  else if tOutcome is not empty
  then ssBkAnswer "warn","Restore Error",tResult,"OK"
end if

Using
<EntryName> is the name of an existing Scrapbook Entry.
<AttachmentName> is the name of a valid attachment.

Error handling
Errors will be in 'the result': Line 1 is "ERR: <error>", line 2 is the command, line 3
is the offending value.
If EntryName does not exist, "ERR: No such Entry" will be returned.
If AttachmentName does not exist, "ERR: No such Attachment" will be returned.

EXAMPLE
This deletes an attachment called "Document.doc" from an Entry called "MyEntry"...

ssBkDeleteAttachments "MyEntry","Document.doc"
put the result into tResult
if tResult is NOT empty then ssBkAnswer tResult

EXAMPLE
This returns the view mode of the current Scrapbook in an answer dialog...

Sets the view mode of the current Scrapbook. Setting the view to the existing view
has no effect.

Error handling
Errors will be in 'the result': Line 1 is "ERR: <error>", line 2 is the command, line 3
is the offending value.
If the parameter is missing, "ERR: Missing parameter - Expected Page, Index, Tree
or History" will be returned.
If the parameter is not understood, "ERR: No such Keyword" will be returned.

Sets the display status of the current Scrapbook. Parking an already parked
Scrapbook has no effect; restoring an unparked Scrapbook has no effect unless the
Scrapbook is minimized in which case it will be restored.

Error handling
Errors will be in 'the result': Line 1 is "ERR: <error>", line 2 is the command, line 3
is the offending value.
If the parameter is not understood, "ERR: No such Keyword" will be returned.

Using
  <EntryName> evaluates to any valid Entry name.
  <Datum> can be any one of "Wrap", "LineNumbering", "Grid", "Bookmarked",
  or "Protected".

Error handling
Errors will be in 'the result': Line 1 is "ERR: <error>", line 2 is the command, line 3
is the offending value.
If the Entry does not exist, "ERR: No such Entry" will be returned.
If Datum is not recognized, "ERR: No such Property" will be returned.

Note that setting some may automatically un-set others if they are incompatible.

EXAMPLE
This gets the line numbering of an Entry called "MyEntry"...

Using
  <EntryName> evaluates to any valid Entry name.
  <Datum> can be any one of "Wrap", "LineNumbering", "Grid", "Bookmarked"
or "Locked".
  <Boolean> is either "True" or "False".

Error handling
Errors will be in 'the result': Line 1 is "ERR: <error>", line 2 is the command, line 3
is the offending value.
If the Entry does not exist, "ERR: No such Entry" will be returned.
If Datum is not recognized, "ERR: No such Property" will be returned.
If Boolean is not "TRUE" or "FALSE", "ERR: Expected TRUE or FALSE" will be
returned.

Note that setting some may automatically un-set others if they are incompatible.

EXAMPLE 1
This displays the line numbering of an Entry called "MyEntry"...

Using
The optional parameter "selected" retrieves the names of the currently selected
icons. If omitted, a list of all available icons is retrieved.

The Result
'The result' is a return-separated list of custom icon names, otherwise an error.

Error handling
Errors will be in 'the result': Line 1 is "ERR: <error>", line 2 is the command, line 3
is the offending value.
If the parameter is not recognized, "ERR: No such Keyword" will be returned.

Using
<plist> is a return-separated list of custom icons to be displayed in the toolbar.

ssBkGetToolbar
ssBkAnswerList the result,"multiple"
put the result into myCustomList
if myCustomList="" then ssBkExitScript
ssBkSetToolbar myCustomList

Error handling
Errors will be in 'the result': Line 1 is "ERR: <error>", line 2 is the command, line 3
is the offending value.
If the operation fails, "ERR: Cannot set the clipboard to that data" will be returned.
If <type> is not recognized, "ERR: No such data type" will be returned.

EXAMPLE 1
This copies the Content field of Entry "MyEntry" to the clipboard as html...

ssBkGetEntryData "MyEntry","Content","HTML"
put the result into tResult
ssBkCopyToClip tResult,"HTML"

Gets the pathname to the current Scrapbook, plugins folder or application folder.
If empty or an unrecognized parameter, the user is presented with a file select
dialog and the result contains the selected file path or "Cancel".

Presents the user with an "Ask" dialog, optionally showing an icon, default text and/or
a dialog window title, and two response buttons: OK and Cancel.

Using
[Icon] is optional. If supplied, the icon id is used. To force a modal display, use
the word "GLOBAL". This has no effect when deployed on OS9 or Windows; if omitted
on OSX, the dialog is displayed as a sheet by default.
[DefaultText] is optional. If supplied, it is the suggested text.
[DialogTitle] is optional. If supplied, it is displayed in the dialog window's titlebar.

ssBkAsk "","What do you want to be called?"
put the result into tResult
if tResult is not "" then ssBkAnswer tResult

EXAMPLE 2
This asks the same question, but with an icon, as modal in all platforms, supplies a
default name and puts a title in the dialog's titlebar:

ssBkAsk "1003 GLOBAL","What do you want to be called?","Alex","A Name is required"
put the result into tResult
if tResult is not "" then ssBkAnswer tResult

Using
[default] is optional. If supplied, it is the suggested file name. If it is a full file path,
the initial directory is also shown.

ssBkAskFile "sample.txt"
put the result into tResult
if word 1 of tResult is "Cancel" then
ssBkanswer "You cancelled."
else ssBkAnswer tResult

Presents the user with a file selection dialog. 'The Result' is either empty or the
full path to the selected file.

ssBkAnswerFile
put the result into tResult
if word 1 of tResult is "Cancel" then
ssBkanswer "You cancelled."
else ssBkAnswer tResult

Using
<URL> can be a file or folder path, a web URL or an eMail address...
- Files and folders should evaluate to the full path name. Note the delimiter must
always be the / character (rather than \ for Windows or : for Macs).
- Web URLs should be in full, prefixed with "http://" or "https://".
- eMail addresses should be prefixed with "mailto:"

Error handling
Errors will be in 'the result': Line 1 is "ERR: <error>", line 2 is the command, line 3
is the offending value.
If the URL evaluates to the current Scrapbook, "ERR: Scrapbook already in use"
will be returned.
If the URL cannot be found, "ERR: 404 URL not found" will be returned.
If an unexpected error occurs, "ERR: <error message>" will be returned.

ssBkLaunchURL "mailto:admin@FlexibleLearning.com"
put the result into tResult
if word 1 of tResult is "ERR:" then
ssBkAnswer tResult
end if

ssBkLaunchURL "http://www.FlexibleLearning.com"
put the result into tResult
if word 1 of tResult is "ERR:" then
ssBkAnswer tResult
end if

EXAMPLE 3
This opens a file on Windows (note the delimiter is '/' and not '\') ...

ssBkLaunchURL "C:/My Documents/myDoc.doc"
put the result into tResult
if word 1 of tResult is "ERR:" then
ssBkAnswer tResult
end if

EXAMPLE 4
This opens a folder on OSX (note the delimiter is '/' and not ':') ...

ssBkLaunchURL "desktop/Applications"
put the result into tResult
if word 1 of tResult is "ERR:" then
ssBkAnswer tResult
end if

Displays the Scrapbook's print dialog with either screen ("print preview") or file
("Web Publishing") options.

Using
<destination> is either "screen" or "file". If not supplied, it defaults to "screen".

Error handling
Errors will be in 'the result': Line 1 is "ERR: <error>", line 2 is the command, line 3
is the offending value.
If the parameter is invalid, "ERR: Expected Screen or File" will be returned.

ssBkPrint "Screen"
put the result into tResult
if word 1 of tResult is "ERR:" then
ssBkAnswer tResult
else if tResult is "Cancel" then
ssBkAnswer "You cancelled."
end if

ssBkAnswer <Type ["GLOBAL"]>,<Heading>,<Text>,<DefaultOption>[,Option2 [,Option3]]

Using
1. Short Form
You can use ssBkAnswer <Text> to display a simple modal dialog with the specified
text message and an "OK" answer button. If you want more than this, use the long
form described next.

2. Long form
Displays a modal dialog that returns the selected option button name. The icon style
and button order will be automatically adjusted for the platorm when deployed.
<Type> determines the icon displayed. Can be empty (no icon), "Stop" (or "Error"),
"Warn", "Query", "Info", or any available image ID (max 64x64). On OSX: The dialog
will display as a sheet by default. To force a modal display, put the word "GLOBAL"
after the type (for example "stop GLOBAL"). This has no effect when deployed on
OS9 or Windows; if omitted on OSX, the dialog is displayed as a sheet by default.
<Heading> is the title of the message. Can have up to two lines, for a title and
subtitle, for example.
<Text> is the message
<DefaultOption> is the default button in the dialog (activated by the Enter or Return
keys).
<Option2> is the second option button (optional)
<Option3> is the third option button (optional)

The Result
'The result' contains the name of the button selected, or an error.

Error handling
Errors will be in 'the result': Line 1 is "ERR: <error>", line 2 is the command, line 3
is the offending value.
Minimum requirement is the DefaultOption. If not supplied, "ERR: No Default" is
returned.

EXAMPLE 1
This displays a dialog with no icon and a single "OK" option...

EXAMPLE 2
This displays a dialog, and on OSX above all other windows, with a single option...

ssBkAnswer "stop GLOBAL","Critical Error Pending","This is NOT a good idea!","OK"

EXAMPLE 3
This displays a dialog using a custom icon, and on OSX as a sheet, with two options...

ssBkAnswer "1038","Delete All","Are you sure?","No","Yes"
if the result is "No" then ssBkExitScript

Using
<List> is a return-separated list.
<MultipleSelection> is "Multiple" or "Single". If not supplied, it defaults to "Single".
Under OSX, the dialog will display as a sheet by default. To force a modal display,
set the third parameter to "GLOBAL". This has no effect when deployed under OS9
or Windows.

The Result
'The result' is either the line/s selected from the list, or "Cancel".

put fld "List" into pList
if the hilite of btn "Multiple Selection" then
put "Multiple" into pMultipleSelect
else put "Single" into pMultipleSelect

if NOT the hilite of btn "As sheet" then
get ssBkAnswerList pList,pMultipleSelect,"GLOBAL"
else get ssBkAnswerList pList,pMultipleSelect

No parameters. Saves the Scrapbook and updates internal issues. If an error is
encountered, notification is automatic but the script will continue.

EXAMPLE 1
This simply saves the Scrapbook...

ssBkCreateEntry "My New Entry"
put the result into tResult
if tResult is not empty then ssBkAnswer tResult
else ssBkSave

Copies the current Scrapbook and saves it as a newly named Scrapbook. The new
name defaults to "Clone of" with the current Scrapbook name, but you can change it
if you wish.

The Result
If successful 'the result' is empty or "Cancel", otherwise an error message.

Error handling
If a problem is encountered it will be in the result as "ERR:" followed by the problem.

EXAMPLE 1
This offers to save a copy the current Scrapbook...

ssBkSaveAs
put the result into tResult
if tResult is not empty and tResult is not "Cancel" then
ssBkAnswer tResult
end if

ssBkAnswer "stop","Rule the World","Do you really want world domination?","No","Yes"
if the result is "No" then
ssBkExitScript
else
ssBkAnswer "Maybe next year, okay?"
end if

No parameters. 'The Result' is the path to the IACin folder from which the Scrapbook
reads input scripts. Note: It includes the terminal delimiter.

No parameters. 'The Result' is the path to the IACout folder to which ssBkIACwrite
writes output messages. Note: It includes the terminal delimiter.

EXAMPLE
This gets the IACout folder path for files written to disk by the ssBkIACwrite command

Saves <message> to a named file. If FileName does not evaluate to a full file path,
the IACout directory will be used (located in the same folder as the Scrapbook).

Short filenames written to the IACout folder will be overwritten without warning.

Using
<message> evaluates to the text to be written to the file.
<FileName> evaluates to a valid file name for the saved file. It can be a short or
full path.

The Result
'The result' is the full filepath if successful, otherwise an error message.

Error handling
Errors will be in 'the result': Line 1 is "ERR: <error>", line 2 is the command, line 3
is the detail.
If the fileName is missing, "ERR: Missing file Name" will be returned.
If the file cannot be written, "ERR: Cannot create File" will be returned.

ssBkCreateEntry "My New EntryName"
put the result into tResult
if "ERR:" is word 1 of tResult then
ssBkIACwrite tResult,"err002.txt"
ssBkExitScript
else .../...

ssBkGetEntryName "Current"
put the result into tEntryName
ssBkGetEntryData tEntryName,"All","HTML"
put the result into tData
# Save file to disk...
ssBkaskFile tEntryName&".html"
put the result into tHTMLFilePath
if tHTMLFilePath = "Cancel" then ssBkExitScript
ssBkIACwrite tData,tHTMLFilePath
# Launch the file...
ssBkLaunchURL tHTMLFilePath

EXAMPLE 3
This saves the current Entry as an html file to the default IACout folder...

ssBkGetEntryName "Current"
put the result into tEntryName
put tEntryName&".html" into tFileName
ssBkGetEntryData tEntryName,"All","HTML"
put the result into tData
# Save file to the IACout folder...
ssBkIACwrite tData,tFileName
# Launch the file...
ssBkLaunchURL the result

Error handling
Errors will be in 'the result': Line 1 is "ERR: <error>", line 2 is the command, line 3
is the detail.
If the fileName is missing, "ERR: Missing file ID" will be returned.
If the file does not exist, "ERR: No such File" will be returned.
If the file cannot be read, "ERR: Cannot open File" will be returned.

Deletes the specified files. Useful as a housekeeping exercise at the end of a script,
unless you need to refer to file contents at a later stage.

Using
The parameter must evaluate to "IACin" (the 'oldScripts' folder in the 'IACin' folder)
or "IACout".

The Result
'The result' is is empty if all files are deleted, otherwise an error.

Error handling
Errors will be in 'the result': Line 1 is "ERR: <error>", line 2 is the command, line 3
is the value.
If the parameter is invalid, "ERR: Expected IACin or IACout" will be returned.
If all files cannot be deleted, "ERR: Cannot delete all Files" will be returned with the
names of the files involved as a return-separated list in the value. The probable
cause is a protected or locked file.

NOTE: Remember that IACout files can be deleted automatically when the
Scrapbook closes, and that IACin files are either deleted or moved to the 'oldScripts'
folder when executed. Both are under the User's control in the IAC Preferences.
You may wish to use the ssBkIACdelFiles command to clean up after yourself in case
the User's settings do not do so for you!

EXAMPLE 2
This deletes all files from the IACin 'oldScripts' directory. Names of files that could
not be deleted are written to a file called 'err0001.txt' in the IACout folder...

ssBkIACdelFiles "IACin"
put the result into tResult
if tResult <> "" then
ssbkIACwrite tResult,"err001.txt"
end if