Softimage SDK Programmer's Guide > Customizing with the SDK > Building and Deploying Customizations >

# Walkthrough: Building an Add-on

This walkthrough shows an easy workflow for working with add-ons and .xsiaddon files. In this walkthrough, we'll build a tool named MyTool and distribute it as an .xsiaddon file. The actual content of MyTool is not what is important; what's important is the workflow.

Create a workgroup

You can build add-ons in the User location, but the recommended location is a workgroup. As you will see, it is easier to test an .xsiaddon if the original add-on files are located on a workgroup.

Workgroups are often shared by many users, but for tool development, it's better to work in a private workgroup, which can be either on the local machine or a network share.

1. In the Softimage main menubar, choose View Layouts Tool Development Environment.

   The Tool Development Environment is a layout that combines many of the most-used Softimage development tools, such as the Plug-in Manager, script editors, the SDK Explorer, and NetView.

2. In the Plug-in Manager, click the Workgroup tab, and then choose File Create.

3. In the Create Workgroup dialog box:

   - In the Workgroup Folder Name box, type a name for the workgroup.

   - Beside the Location of Workgroup box, click and locate the folder that will contain the workgroup.

4. Click OK to create the workgroup. Softimage automatically connects to the workgroup, and the workgroup appears in the plug-in tree.

Create the Add-on Directory

If you intend to distribute a tool, we recommend you create an Add-on directory in your workgroup. This separates your files from any other content in the workgroup, and makes it easy to package the .xsiaddon file.

1. In the Plug-in Tree, right-click your workgroup and choose New Add- Directory.

2. In the Create Add-on Directory dialog box, type "MyTools" as the name for the add-on.

   In the Plug-in Tree, a new Addon folder node appears under the workgroup.

Add Help for the Add-on

Softimage includes a convenient workflow for establishing Help files and contact information for the Add-on. By using a standard naming scheme for the help files Softimage is able to offer context-sensitive help for custom tools just as it does for internal features.

1. In the Plug-in Tree, right-click the MyTool add-on and choose New Add-on Help.

   The Add-on Documentation Wizard appears.

2. If you want to see examples of add-on help pages, click the Help tab and then click Show Me.

3. In the Description box, type some a brief description of the add-on.

   This short description is displayed on the add-ons page of XSI Local, and is inserted into the add-on help page (an HTML file).

4. Use the default image and template.

   Image is a 56x56 JPG file that is used as an icon for the add-on.

   Template is a simple HTML page. The wizard replaces the tokens %DESCRIPTION% and %ADDONIMAGE% with the description and image specified in the wizard.

5. Click OK to generate the help page. The wizard will open the html file in a text editor, allowing you to add more details to the description of your add-on.

   The wizard does not modify the plug-in source code. The add-on help is not specified by setting the Help property of the plug-in or plug-in items.

   Instead, the wizard generates four files in the Add-on directory:

   - netview_<Addon>.htm

   - netview_<Addon>.jpg

   - netview_<Addon>.txt

   - netview_<Addon>.xml

   Softimage looks for these files and, if they exist, uses them as the add-on help. See Documenting Add-ons.

6. To view the help, do one of the following:

   - In the Plug-in Tree, right-click an Add-on and choose Help.

   - In NetView, go to the add-ons page of XSI Local.

   - If the add-on includes a self-installing property, then in the property page, click the ? icon in the title bar.

7. The generated help files do not appear in the plug-in tree, but you can easily access them by choosing Browse from the Add-on context menu:

   The browser shows the folders and files associated with the MyTool addon, which so far consists only of the documentation files.

Create Add-on Content

An add-on can contain any number of self-installing plug-ins, shaders, toolbars, scripts, images, and other content. Basically, any Softimage customization or auxiliary file can be included in an add-on (the SDK example workgroup provide some good examples of possible add-ons).

Generating content with wizards

Softimage includes wizards for generating self-installing plug-ins such as shaders, commands, operators, properties, and events. For example, to generate a self-installing command in an Add-on directory, right-click the Plugins folder in the add-on and choose New Command.

Softimage also includes a wizard for creating toolbars. You can run this wizard by right-clicking Toolbars (for the Toolbar Wizard).

Moving content to the add-on

Using the plug-in tree, you can drag plug-ins, toolbars, and views from another location to your add-on.

You can also move files into the Add-on directory using Windows Explorer, a command prompt, or any other external file manager. The Plug-in Tree does not support every possible type of Add-on content, so for files like layouts, keymaps, and documentation, you need to move files through the file system.

Important

When you add files to an addon, you must put the files in the correct folders. Softimage finds files by looking in specific sub-folders of an Add-on location. For example, toolbar (.xsitb) files must be put in the Application\Toolbars folder, so in this case, toolbars must be put in C:\XSITools\Addons\Foo\Application\Toolbars.

Package the .xsiaddon

When you're ready to distribute your add-on, you have two choices:

- If the add-on is for internal usage within your company, you can distribute the add-on by copying it to a shared workgroup location on the network. You can do this using an external file manager such as Windows Explorer.

- If the add-on is to be distributed to external users, who do not have access to the same network, then you use an .xsiaddon file.

An .xsiaddon file is single file that contains a compressed version of all the files of an Add-on location.

Previous versions of Softimage had a Package Add-on dialog box that required you to add files one at a time. This dialog is still available, but now there is an easier-to-use Package Location option.

Before you package an add-on, make sure the add-on directory contains only the files and folders you want to distribute:

- Delete any temporary files and folders.

- Compile Release versions of any DLLS (not Debug versions).

Note that you can exclude directories when you create the add-on package. For example, if you keep any C++ source code in a separate folder, you can just exclude the folder from the package.

To package the add-on

1. In the Plug-in Tree, right-click the MyTool add-on and choose Package Add-on.

2. In the Package Location Options dialog box, set the packaging options:

   - Source is the location of the Add-on directory. The .xsiaddon file will contain everything under the source folder.

   - Destination is where the .xsiaddon file will be created. You may want to add a version number to the file name, since .xsiaddon files do not support versioning.

   - Directories to Exclude is a semi-colon (;) separated list of folders that you do not want to include in the .xsiaddon file.

   - Author and Description are optional. Information entered here is saved in netview_MyTool.xml, and reused each time you repackage the add-on. The information is also displayed on the add-ons page of XSI Local.

3. Click OK to generate the .xsiaddon file. If the file contains .dlls or other large content it may take a few minutes to generate the output file.

   The .xsiaddon file is an xml file, so it is possible to view its contents and even make minor modifications, such as filling in the Usage or Platform information.

Test the add-on

To test the .xsiaddon, you could move it to a different computer or ask someone to try it, but you can also do it on your own computer.

1. Remove the original MyTool from memory, to avoid conflict errors and other confusion. Because the add-on is in a workgroup, all you have to do is unload (disable) the workgroup.

   On the Workgroups tab, clear the check box beside the XSITool workgroup.

   This unloads the self-installing plug-ins and other content of the Add-on. Note that some less-common workgroup files, such as keymaps and layouts, are not unloaded until Softimage is restarted.

2. Install the MyTool add-on in the User location or in another workgroup location. Right-click the location and choose Install .xsiaddon.

3. In the Select Add-on File dialog box, locate the MyTool.xsiaddon file (it is in C:\My Documents\XSITools\Addons) and select it.

   The add-on appears in the plug-in tree under the location where you installed the add-on.

4. Now you can test the add-on. For example, make sure that all commands, toolbars, and other content work properly.

   You should also check that your help works.

   In NetView, click XSI Local and then click add-ons, and verify that your add-on is listed:

5. When you finish testing, uninstall the MyTool add-on and reconnect to your original workgroup.

Repackaging the .xsiaddon

Any time that you modify or update a tool (for example, by adding new content or new features, or by fixing a bug) you need to repackage the .xsiaddon so you can redistribute it to your users.

To repackage an add-on, just package it again, but perhaps with a different file name. Repackaging takes just a few mouse clicks, because all the information you entered when you first packaged the add-on is automatically filled in when you repackage.