LIVEXTENSIONS

Are you a ToolBook OpenScript programmer and interested in creating a LiveXtension Tool?

 

The following information is intended to give an experienced OpenScript programmer the necessary details needed in order to successfully create a LiveXtension.

 

What is a LiveXtension?

A LiveXtension is just a regular .TBK file that does some task. However it is important for you to understand how your tool is shown.

 

• When the LiveXtension interface is being launched, what happens is that ToolBook is told to show a viewer of a book [it is named _index.tbk] located on the SumTotal web site. The _index.tbk book is the main LiveXtension interface.
• When you launch your Tool from the LiveXtension interface, your tool is shown in a viewer of the _index.tbk file.

 

What can a Developers Exchange Tool do?

A LiveXtension can do virtually anything a normal book can do. For example a very simple tool to show the current date would be a one page book with a single button in it with the following code on the button.

 

to handle buttonClick

  request sysDate

end

 

A slightly more complex task would be to show the user how many Pages and Backgrounds are in their book. This is more complex because your Tool has to access information about their book. Here is a sample of one way to do this:

 

-- Show the PageCount and BackgroundCount of the user's book

to handle buttonClick

  userBook = parent of mainWindow

  tp = pagecount of userBook

  tb = backgroundcount of userBook

  request tp & CRLF & tb

end

 

Notice the need to tell the code to fetch the information from the parent of the mainWindow (which is essentially the user's loaded book). If you fail to include such logic the code would instead fetch the information from your tool, which is not the desired effect in this case.

 

-- Show the PageCount and BackgroundCount of the Tool itself

to handle buttonClick

  tp = pagecount of this book

  tb = backgroundcount of this book

  request tp & CRLF & tb

end

 

Special Settings Needed for your Tool

SUMMARY TAB

On the Summary tab of the Book Properties there are several values which need to be populated in order for your Tool to properly import as a local tool.

 

    Book Title

    This is the name of your tool (not the file name).

    For example: Automatic Buttonizer

 

    Author

    Your Name

 

    Description

    A summary description of what the tool does

MODAL VS NON-MODAL

You can choose to have your Tool shown in a Modal or Non-Modal window. By default your tool will appear in a Modal window. If you wish to make this a non-modal window, set the following book user property of your tool:

 

    devex_modal = false

EXITING YOUR BOOK

Recall that your tool is being shown in a Viewer of another book (_index.tbk). When exiting your tool, all you need to do is close the window you are in. You would not want to perform an EXIT command.

 

-- programmatically closing the window

to handle buttonClick

  close this window

end

 

Letting the user click the X in the corner of the tool's window is a valid way to allow them to exit, which works well in a stand-alone tool or as a LiveXtension. However if you wish to provide an Exit button, use this code in the Exit button.

 

-- programmatically closing the window (or exiting)

to handle buttonClick

  if shownBy of objectContainer(self,"page") = mainWindow

  send exit

 else

  close this window

 end

end

ADDING YOUR TOOL AS A SYSTEM BOOK

When you launch a LiveXtension, the tool is shown in a viewer of _index.tbk, as discussed above. This way of showing another book has a unique side effect in that normal messages sent up through the ToolBook messaging hierarchy from the users book (the MainWindow) are never sent to your tool.

 

This may not be an important consideration for your tool but in the case of the Web Safe Color Tray (for example), it is a requirement of the tool to be able to not only be Non-Modal, but also be able to tell what is happening in the MainWindow. For example, in the case of the Web Safe Color Tray, it is critical that the Color Tray know when the user selects an object in the MainWindow.

 

The way to get your Tool into the normal messaging hierarchy is to push your tool onto the SYSBOOK stack (note this does not mean your tool has to have a .SBK extension). This is a little tricky to do as you have to essentially override the normal opening mechanism of the LiveXtensions, and then handle the removal of your tool from the SYSBOOK stack when your tool closes.

 

Below is our recommended way to create a Non-Modal Tool which pushes itself onto the SYSBOOK stack and then properly removes itself when the tool closes. You may find other approaches which work equally well for you.

 

• Create your tool, giving it a normal .TBK extension.
• Do Not set the NON-MODAL setting outlined earlier in this article.
• Create a Viewer in your book to host your tool, having the default page of your viewer point to the proper page of your book to show your tool's users interface (likely page 1).
• Add the script below to your book (a portion goes in your Book Script and a portion in your Viewer Script).

 

-- this script goes in your book script

-- you'll need to modify ONE line of the script below

to handle enterBook

 if (self is in TARGET) AND (parent of this window) IS NOT (this book)

   close this window

   sysSuspend = false

   in mainWindow

     push (name of self) onto sysbooks

   end

   sysSuspend = true

   --> specify your viewer name on this next line

   show viewer "tray" of self

 end

 forward

end

 

-- this script goes in your viewer script

-- you should not need to modify any of the code below

to handle closeWindow

 forward

 fileRef = name of this book

 step k from 1 to itemCount(sysbooks)

   curSysbook = item k of sysbooks

   if curSysbook = fileRef

     clear item k of sysbooks

   end

 end

end

 

---

KEYWORDS: 23202 P5125

---