Knowledge Base

TIPS FOR CREATING YOUR OWN TOOL
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.

1. Create your tool, giving it a normal .TBK extension.
2. Do Not set the NON-MODAL setting outlined earlier in this article.
3. 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).
4. 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

Provide Anonymous Feedback About This Article

Are you interested in providing feedback to SumTotal about this article? Yes