The Scripter's Scrapbook API

The Scripter's Scrapbook API
The personal reference library for all programmers

Version: 1.22
Issued: 1 October 2007
by www.FlexibleLearning.com

• Interactive Handbook: Revolution users may wish to download an interactive version of this Handbook in stack format.

• API Sample: A sample PlugIn of API widgets is available here.

• IAC Sample: IAC script samples are here.

Note that the API requires version 5.2 or later of The Scripter's Scrapbook. The current version of The Scripter's Scrapbook is available here. Commands that require a later version are indicated.

Contents...

ssBkAPIerrorDialog

ssBkGetContextList

ssBkGetEntryName

ssBkGetIndexCount

ssBkGetIndexEntries

ssBkShowIndexEntries

ssBkGetEntryData

ssBkSetEntryData [modified in v5.2.11]

ssBkCreateEntry [modified in v5.2.11]

ssBkRenameEntry

ssBkDeleteEntry

ssBkAskExport [new in v5.2.10]

ssBkImportBackup

ssBkGetAttachments

ssBkSetAttachments

ssBkRestoreAttachments

ssBkDeleteAttachments

ssBkCopyToClip [new in v5.2.15]

ssBkGetPath [new in v5.2.13]

ssBkIACgetInDir

ssBkIACgetOutDir

ssBkIACdelFiles

Scripting the Scrapbook...

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'.

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.

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.

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.

Good luck, and happy scripting!
www.FlexibleLearning.com

How it works

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.

This is what happens...

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.

What's in a Script?

IAC scripts should be written as ASCII text files either using the built-in ScriptMaker, or NotePad (PC), SimpleTest (Mac) or TextEdit in plain mode (OSX) 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"

3. IF... Then...
Conditional statements are straightforward...

  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,"Code"
    put the result into tData
  end if
  ssBkIACwrite tData,"selectedCode.txt"

Script tips

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.

ssBkGetIndexEntries
put the result into tEntriesList

Error Messages
(See also Error Handling)

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

This will not work...

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 ...

Short syntax
The following are equivalent...

  if tResult is not empty
  if tResult is not ""
  if tResult <> ""

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'...

ssBkGetTools
ssBkAnswerList the result

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

put "Apples" &CR& "Pears" &CR& "Oranges" into tList

Or use format as an alternative...

put format("Apples\nPears\nOranges") into tList
ssBkAnswerList tList

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"

Writing Plugins...

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.

Types of Error

See also Using the IAC:Script tips and ssBkAPIerrorDialog

There are 3 types of error...

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.

Even if the script compiles, it may still have an execution or a command bug...

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).

Catching Errors

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.

Using ssBkIACwrite

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

Script Testing

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

ssBkAPIerrorDialog "True" | "False" | "get"

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".

To obtain the current setting...
"GET" - Retrieves the current setting.

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...

If "true" the 'Cancel/Continue' dialog is presented:

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

If "false", the 'Cancel/Continue' dialog is not presented:

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

"GET" - Retrieves the current setting...

ssBkAPIerrorDialog "get"
put the result into tDialogSetting

ssBkGetVersion ["longDate" | "shortDate | "dateItems"]

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

ssBkGoEntry <EntryName | "next" | "prev" | "fwd" | "back" | "first" | "last">

See also: ssBkGetEntryName

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.

The Result
If sucessful 'the result' is empty, 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 EntryName does not exist, "ERR: No such Entry" will be returned.
If the keyword cannot be implemented, "ERR: Not applicable" will be returned.

EXAMPLE 1

ssBkGoEntry "next"

EXAMPLE 2

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

ssBkGetContextList <ContextType>

Retrieves the listings for each ContextType.

See also ssBkSetEntryData.

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...

ssBkGetContextList "Categories"
put the result into tResult

EXAMPLE 2
This answers the currently defined Languages...

ssBkGetContextList "Languages"
ssBkAnswer the result

EXAMPLE 3
This puts the currently defined Platforms...

ssBkGetContextList "Platforms"
put the result into tResult

ssBkOpenTools <ToolName/s>

Opens the specified Scrapbook tool/s and/or plugin.

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.

ssBkOpenTools will bring an already open tool to the front.

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...

ssBkOpenTools format("Format\nCategories\nContext\nSSBkChat")

ssBkGetPlugins [<Type>]

See also: ssBkOpenTools

Retrieves a return-separated list of available plugins.

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.

EXAMPLE
This opens the selected plugins...

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

ssBkGetEntryName <keyword>

Retrieves the name of the specified Entry in the current Scrapbook.

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

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

Use ssBkGoEntry <keyword> to preserve History.

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

EXAMPLE

ssBkGetEntryName "next"
ssBkAnswer the result

ssBkGetIndexCount

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

EXAMPLE

ssBkGetIndexCount
ssBkAnswer "info","Count of Entries",the result,"OK"

ssBkGetIndexEntries <Platform/s>,<Language/s>,<Category/s>, <StatusType/s>

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"

ssBkShowIndexEntries <EntryNames>

Displays the <EntryNames> in the Index.

Using
<EntryNames> is a return-separated list of valid Entry names.

Use ssBkGetIndexEntries for a list, or ssBkAnswerList for a User selection.

The Result
It returns the number of sucessfully displayed Entries.

EXAMPLE 1
This is the script of the above button "Show Bookmarked"...

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","",""

EXAMPLE 2
This is the script of the above button "Show Protected"...

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

EXAMPLE 3
This is the script of the above button "Show All"...

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

EXAMPLE 4
This is the script of the above button "Try Me"...

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

ssBkGetEntryData <EntryName>,<Datum> [, "HTML"]

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.

The Result
'The Result' is the text contents of the Entry as requested.

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 is not recognized, "ERR: No such Keyword" will be returned.

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"

ssBkSetEntryData <EntryName>, <Datum>, <Value> [, "HTML"]

See also ssBkGetContextList

Sets the data for the Entry <EntryName>.

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.

The Result
'The Result' is either empty if successful, 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 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, it 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...

ssBkSetEntryData "MyEntry","Platforms","OSX,WinOS"

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...

ssBkSetEntryData "MyEntry","Code","This is a <B>test</B>","HTML"

ssBkCreateEntry <EntryName>[,"AskContext"]
[Updated in 5.2.11 to include "AskContext"]

Creates a new Entry with the name <EntryName>. 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.

The Result
'The Result' is either empty if successful, 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 <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

ssBkRenameEntry <CurrentEntryName>,<NewEntryName>

Renames an Entry.

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

The Result
'The Result' is either empty if successful, 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 <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

ssBkDeleteEntry <EntryName> [, <Dialog>]

Deletes an Entry.

Using
<EntryName> evaluates to any valid Entry name.

Use ssBkGetAttachments to check if any files are attached.

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.

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.

EXAMPLE 1
This deletes an Entry called "My Entry" without any warning...

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 <EntryName>

Omits an Entry from the Index.

Using
<EntryName> evaluates to any valid Entry name.

The Result
'The Result' is either empty if successful, 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 EntryName does not exist, "ERR: No such Entry" will be returned.
If EntryName is the only listed Entry, "ERR: Cannot omit Entry" will be returned.

EXAMPLE
This omits an Entry called "My Entry" from the Index...

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

ssBkAskExport
[Introduced in ssBk v5.2.10]

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 fields (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

ssBkImportFile [<FilePath/s>]

Converts Files to Entries.

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."

ssBkImportBackup [<FilePath>]

Offers to restore a Scrapbook backup file.

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.

EXAMPLE
This offers to restore a backup...

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

ssBkGetAttachments <EntryName>

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

Using
<EntryName> evaluates to any valid Entry name.

The Result
'The Result' is either a return-separated list of attachments, 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 EntryName does not exist, "ERR: No such Entry" will be returned.

EXAMPLE
This retrieves the names of any attachments for an Entry called "My Entry"...

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

ssBkSetAttachments <EntryName>[,<FilePath>]

Adds an attachment to an Entry.

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.

EXAMPLE 1
This attaches a selected file to an Entry called "MyEntry"...

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

EXAMPLE 2
This attaches a specified file to an Entry called "MyEntry"...

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

ssBkRestoreAttachments <EntryName>,<AttachmentName> [,<Destination>]

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.

Use ssBkGetAttachments to retrieve a list of the Entry's attachments.

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.

The Result
'The Result' is empty if successful, or "Cancel".

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.

EXAMPLE
This restores an attachment for an Entry called "My Entry" to a file...

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

ssBkDeleteAttachments <EntryName>,<AttachmentName>

Deletes an attachment from an Entry.

Use ssBkGetAttachments for a list of attached files.

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

The Result
If successful 'the result' is empty, 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 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

ssBkGetView

(See also ssBkGetParked)

No parameters. Gets the 'view mode' of the current Scrapbook.

The Result
'The result' is "Page" or "Index" or "Tree" or "History".

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

ssBkGetView
ssBkAnswer the result

ssBkSetView <mode>

(See also ssBkSetParked)

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

Using
<mode> can be either "Page" or "Index" or "Tree" or "History"

The Result
If successful 'the result' is empty, 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 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.

EXAMPLE
This sets the view to display the 'tree' index...

ssBkSetView "tree"

ssBkGetParked

(See also ssBkGetView)

No parameters. Gets the display status of the current Scrapbook.

The Result
'The result' is "parked" or "unparked".

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

ssBkGetParked
ssBkAnswer the result

ssBkSetParked <status>

(See also ssBkSetView)

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.

Using
<status> can be any one of "Park", "Restore" or "Toggle".

The Result
If successful 'the result' is empty, 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 understood, "ERR: No such Keyword" will be returned.

EXAMPLE
This parks the current Scrapbook...

ssBkSetParked "park"

ssBkGetDisplay <EntryName>,<Datum>

Gets the specified Datum for the Entry <EntryName>.

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

The Result
If successful 'the result' is TRUE or FALSE, 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 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"...

ssBkGetDisplay "MyEntry","LineNumbering"
ssBkAnswer the result

ssBkSetDisplay <EntryName>,<Datum>,<Boolean>

Sets the specified Datum for the Entry <EntryName>.

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".

The Result
If successful 'the result' is empty, 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 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"...

ssBkSetDisplay "MyEntry","LineNumbering","TRUE"

EXAMPLE 2
This bookmarks an Entry called "MyEntry"...

ssBkSetDisplay "MyEntry","Bookmarked","TRUE"

ssBkGetToolbar ["selected"]

Gets an alphabetical list of custom toolbar icon names.

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.

EXAMPLE 1
This shows a list of all available custom toolbar icons...

ssBkGetToolbar
ssBkAnswer the result

EXAMPLE 2
This shows a list of the currently selected custom toolbar icons...

ssBkGetToolbar "selected"
ssBkAnswer the result

ssBkSetToolbar <plist>

Sets custom toolbar icons.

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

The Result
'The result' will always be empty.

Error handling
Unrecognized icon names are ignored.

EXAMPLE
This displays selected icons...

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

ssBkCopyToClip <data>,<type>

(See also ssBkGetEntryData)

Places the <data> formatted as <type> onto the clipboard.

Using
<type> can be either "HTML" or "TEXT". If empty, it means TEXT.

The Result
If successful 'the result' is empty, 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 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"

EXAMPLE 1
This grabs the Scrapbook version and puts it onto the clipboard...

ssBkGetVersion "A"
ssBkCopyToClip the result,"TEXT"

ssBkGetPath <type>
[Introduced in 5.2.13]

(See also ssBkAskFile and ssBkAnswerFile)

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".

Using
<type> can be either "Scrapbook" or "PlugIns" or "App" or empty.

The delimiter used is / instead of the DOS \ or the Mac :

EXAMPLE 1
This returns the full path to the current Scrapbook...

ssBkGetPath "Scrapbook"
ssBkAnswer the result

EXAMPLE 2
This returns the path to the current plugIns folder...

ssBkGetPath "PlugIns"
ssBkAnswer the result

ssBkAsk <[Icon] ["GLOBAL"]>,<Prompt>,[DefaultText][,DialogTitle]

(See also ssBkAskFile)

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.

The Result
'The Result' is either empty or the User's text.

EXAMPLE 1
The simplest form of the dialog, displaying as a sheet in OSX:

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

ssBkAskFile [default]

(See also ssBkAnswerFile and ssBkLaunchURL)

Presents the user with a "Save as..." dialog.

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.

The Result
'The Result' is either empty or the full path to the file.

The delimiter used is / instead of the DOS \ or the Mac :

EXAMPLE
This returns the full file path from a "Save as..." dialog:

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

ssBkAnswerFile

(See also ssBkAnswerFile and ssBkLaunchURL)

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

The delimiter used is / instead of the DOS \ or the Mac :

EXAMPLE
This returns the full path to a selected file...

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

ssBkLaunchURL <URL>

(See also ssBkAskFile and ssBkAnswerFile)

Launches an external process.

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:"

The Result
'The Result' is either empty 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 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.

EXAMPLE 1
This opens your default email client...

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

EXAMPLE 2
This opens a web page...

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

ssBkPrint <destination>

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".

The Result
'The Result' is either "Cancel" or empty.

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.

EXAMPLE
This displays the built-in Print Preview dialog...

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]]

Displays a modal dialog.

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...

ssBkAnswer "Hello World"

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

ssBkAnswerList <List>,<MultipleSelection> [,"GLOBAL"]

This displays a selection list with "OK" and "Cancel" options.

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".

EXAMPLE
This is the script of the "Do it" button...

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

put the result into tResult
ssBkAnswer tResult

ssBkSave

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...

ssBkSave

EXAMPLE 2
This creates an Entry and then, if successful, saves the Scrapbook...

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

ssBkSaveAs

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

ssBkExitScript

Immediately terminates a script.

EXAMPLE
This exits the script if the user clicks "No"...

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

ssBkIACgetInDir

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

The delimiter used is / instead of the DOS \ or the Mac :

EXAMPLE
This gets the IACin folder path for script input files...

ssBkIACgetInDir
ssBkAnswer the result

ssBkIACgetOutDir

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

The delimiter used is / instead of the DOS \ or the Mac :

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

ssBkIACgetOutDir
ssBkAnswer the result

ssBkIACwrite <message>, <FileName>

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).

See also ssBkIACdelFiles to clean up.

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.

EXAMPLE 1
Simple error handling...

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

EXAMPLE 2
This saves the current Entry as an html file chosen by the user...

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

ssBkIACpeek <FileName>

Gets the contents of a data file written by ssBkIACwrite to the IACout folder.

The delimiter used is / instead of the DOS \ or the Mac :

Using
<FileName> evaluates to the name of file in the default folder.

The Result
'The result' is the contents of the file, 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 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.

EXAMPLE
This gets the contents of an IAC file...

ssBkIACpeek "A12345Zz.txt"
ssBkAnswer the result

ssBkIACdelFiles <"IACin" | "IACout">

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 1
This deletes all files from the IACout directory...

ssBkIACdelFiles "IACout"

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