VISE X 5.0 Users Guide

VISE X 5.0 Users Guide
User’s Guide
VISE X
release 5.0
revised October 24, 2011
© 2003-2012 DR MyCommerce, Inc. All rights reserved.
VISE X User’s Guide
This manual, as well as the software described in it, is furnished under license and may be used or
copied only in accordance with the terms of such license. The content of this manual is furnished for
informational use only, is subject to change without notice, and should not, in and of itself, be construed as a commitment by DR MyCommerce, Inc. DR MyCommerce, Inc. assumes no responsibility
or liability for any errors or inaccuracies that may appear in this book. The copyrighted software that
accompanies this manual is licensed for use by the Licensee only in strict accordance with the Software License Agreement, which the Licensee should read carefully before commencing use of the software. Except as permitted by such license, no part of this publication may be reproduced, stored in a
retrieval system, or transmitted, in any form or by any means, electronic, mechanical, recording, or
otherwise, without the prior written permission of DR MyCommerce, Inc.
Contact Information
MindVision
826 P Street
Suite 300
Lincoln, NE 68508
USA
Phone:
Fax:
E-mail:
Web:
(402) 323-6600
(402) 323-6611
sales@mindvision.com
http://www.mindvision.com
Contents–i
Table of Contents
Table of Contents
Section 1 Getting Started
Chapter 1-About VISE X
Why Use VISE X? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1
About the Compression Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1
Localization Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1
About VISE X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1
New Features in VISE X 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Lion Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Intel-Native Builder Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Information for Installer VISE Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Application File and Folder Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Product Comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
Installer VISE 8.5 Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
External Code Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
Chapter 2-Getting Started with VISE X
System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1
Contents of the Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1
Installing VISE X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Choosing a Destination for the Install . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Choosing Easy Install or Custom Install . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Completing the Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
About the VISE X Extensions and VISE X Locations Folders . . . . . . . . . . . 2-3
Registering VISE X. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
VISE X Version Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
VISE X User’s Guide
Contents–ii
Section 2 Building Installers
Chapter 3-Creating an Archive
About Archives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1
Creating a New Archive. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
The Extended Add Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
Displaying Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3
Selecting Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3
Shortcuts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3
Adding Files to the Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3
Creating an Installation Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4
Catalog Only. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4
Saving an Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4
Changing File Names in the Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5
Removing Files from the Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5
Modifying Archive Preferences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5
Verifying and Updating an Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6
Verifying the Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6
Bringing the Archive Up-To-Date. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7
Chapter 4-Creating Packages And Assigning Files
About Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
About Sub-Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
Package Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3
List Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7
Creating a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7
Edit Package options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8
Creating Package Separators and Mutual Exclusive Groups . . . . . . . . . . . 4-10
Restarting After Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10
Creating a Sub-Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11
Creating a List Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12
Assigning a Gestalt to the Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14
Language and Region Gestalts for Packages . . . . . . . . . . . . . . . . . . . . . . . 4-15
Package Build Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17
Adding an Icon to a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-21
Rearranging the List of Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-22
Deleting a Package. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-23
Assigning Items to Packages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-23
Assigning Items in the Packages popmenu . . . . . . . . . . . . . . . . . . . . . . . . 4-24
Assigning Items to Packages in the Archive Window . . . . . . . . . . . . . . . . 4-25
Chapter 5-Creating Action Items
What Are Action Items? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1
Basic Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
Creating an Action Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
Entering General Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
Entering <Action> If Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
Entering What to <Action> Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
Items Found Using Search Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
Find Action Item. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
Archive Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8
Action Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-18
VISE X User’s Guide
Contents–iii
Find Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-18
Delete Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-19
Copy Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-20
Move Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-22
Rename Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-23
Alias Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-25
Message Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-26
Display Form Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-29
Set Variable Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-29
Test Variable Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-31
Jump Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-32
Stop Installation Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-34
Sub-launch Action Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-35
Launch URL Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-38
Edit Text File Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-39
Dock/Startup Items Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-43
Check Permissions Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-45
Comment Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-47
UNIX Script Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-48
Saving an Action Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-49
Replace Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-50
Assigning External Codes to Action Items . . . . . . . . . . . . . . . . . . . . . . . . 5-51
Identifying Action Items In the Archive Window . . . . . . . . . . . . . . . . . . . . . . . . . . 5-53
Duplicating Action Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-54
Renaming Action Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-55
Correct Placement of Action Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-55
Assigning Action Items to Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-55
Chapter 6-Assigning External Code
About External Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1
Adding External Code to an Installer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2
Declaring External Code in an Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3
Editing External Code Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6
Deleting External Code Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6
Specifying When to Call External Code . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6
Chapter 7-Creating and Editing Gestalt Calls
About Gestalt Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1
Creating and Modifying Gestalts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1
Creating a Gestalt Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3
Creating a Java Gestalt Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4
Chapter 8-Setting Up Disk Information
Setting Up Disk Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1
Chapter 9-Setting File and Folder Options
Changing File and Folder Options. . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting File and Folder Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Archive Window . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Get Info Window. . . . . . . . . . . . . . . . . . . . . . . . . .
Shadow Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example of Shadowing a File . . . . . . . . . . . . . . . . . . . . . . . . .
VISE X User’s Guide
. . . . . . . . . . 9-1
. . . . . . . . . . 9-2
. . . . . . . . . . 9-2
. . . . . . . . . . 9-2
. . . . . . . . . . 9-3
. . . . . . . . . . 9-4
Contents–iv
Example of Shadowing a Folder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4
Notes on Shadow Items. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-5
Item Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6
Changing an Item’s Long Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6
Changing a File’s Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6
Changing a File’s Region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6
Changing a File’s Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-7
Changing a File’s Creator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-7
Installing the Item Based on an Action Item . . . . . . . . . . . . . . . . . . . . . . . 9-7
Install To Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-7
Domain Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-9
Merging Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-13
Installing a File or Folder To Another Folder in the Archive . . . . . . . . . . 9-13
Replacing Existing Items on the Target System. . . . . . . . . . . . . . . . . . . . . 9-14
Assigning Build Directives to Files and Folders . . . . . . . . . . . . . . . . . . . . 9-16
Storing the Item Uncompressed in a Disk Image or Folder . . . . . . . . . . . 9-17
Installing the Item Based On a Gestalt Check . . . . . . . . . . . . . . . . . . . . . 9-18
Assigning an Item to Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-19
Calling External Codes Associated with an Item . . . . . . . . . . . . . . . . . . . 9-19
Open After Installing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-20
Deleting the Item During Uninstalls . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-20
Restarting After Installing an Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-20
Don't Install Folder (Placeholder) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-21
Synchronizing Dates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-21
Installing Application Bundles on Mac OS X. . . . . . . . . . . . . . . . . . . . . . 9-21
Including an Uninstall Function in the Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-22
Setting Up Your Archive For Uninstalls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-22
Symbolic Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-22
Locking File or Folder Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-23
Folder Default Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-23
About Folder Default Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-24
Setting Group and Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-25
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-26
Setting Group for an Install Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-26
Setting Permissions for an Install Item . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-26
Setting the Owner of an Install Item to Root . . . . . . . . . . . . . . . . . . . . . . 9-27
Chapter 10-Setting Installer Options
Installer Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1
Installer Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1
Designing the Interface Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2
Choosing the Default Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2
Setting the Default Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2
Choosing the Installer Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2
Choosing the Default Install Location . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-6
Adding Text for Display During Easy Install . . . . . . . . . . . . . . . . . . . . . . 10-8
Showing Uninstall in the Installer Popmenu. . . . . . . . . . . . . . . . . . . . . . . 10-9
Creating a Standalone Uninstaller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-10
Adding Text for Display During an Uninstall. . . . . . . . . . . . . . . . . . . . . 10-11
Adding Read Me and License Agreements to the Installer. . . . . . . . . . . . . . . . . . . 10-11
Assigning a Read Me File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-12
Attaching a License Agreement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-13
Extra Installer Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-15
VISE X User’s Guide
Contents–v
Installer Log File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-15
On-line Registration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-16
Adding a Splash Screen and Background Image . . . . . . . . . . . . . . . . . . . 10-16
Adding a Splash Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-17
Adding a Background Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-17
Designing the Installer’s Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-18
Including or Excluding Warnings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-18
Choosing Installation Destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-19
Miscellaneous Behavior Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-20
Sub Launch Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-21
Installer Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-22
Assigning a Custom Icon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-22
Assigning Minimum Requirements for Installation . . . . . . . . . . . . . . . . . 10-23
Setting an Installer Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-23
Adding Advanced Features to Your Installer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-25
Compressing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-26
Adding Files to an Existing Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-27
Assigning a Localization File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-27
Assigning External Codes to an Installer . . . . . . . . . . . . . . . . . . . . . . . . 10-28
Installer Settings for Web Installers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-29
Saving Installer Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-30
Selecting Installer Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-31
Defaulting Installer Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-31
Deleting Installer Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-34
Supporting Multiple Users Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-35
Chapter 11-Adding Billboards to an Installer
Billboards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1
Supported File Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2
Recommended Sizing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2
Billboard Display Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2
Assigning Billboards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2
Chapter 12-Generating Archive Reports
Archive Reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1
Generating Archive Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-3
Report Output Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-4
Chapter 13-Finding Items in an Archive
Find Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-1
Chapter 14-Building the Final Installer
Before the Final Build . . . . . . . . . . . . .
Build Targets . . . . . . . . . . . . . . . . . . . .
Building a Debug Installer . . . . . . . . . .
Building the Release Installer . . . . . . . .
....
....
....
....
...
...
...
...
....
....
....
....
...
...
...
...
....
....
....
....
...
...
...
...
...
...
...
...
....
....
....
....
...
...
...
...
. . 14-1
. . 14-1
. . 14-3
. . 14-5
Creating a CD Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Catalog Only Question. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Create a CD Installer Build Destination. . . . . . . . . . . . . . . . . . . . . . . .
Set Installer Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . 15-1
. . 15-1
. . 15-3
. . 15-5
Chapter 15-Creating CD Installers
VISE X User’s Guide
Contents–vi
Building the CD Installer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-5
Maintaining Finder Icon Positions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-5
File Compression Options for CD-ROM Installations . . . . . . . . . . . . . . . 15-5
Chapter 16-Maintaining Archives
Bringing the Archive Up To Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-1
Verifying an Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-4
Validating Paths. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-4
Section 3 Building Updaters
Chapter 17-About VISE X Updaters
Why Use an Updater? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-1
Why Use VISE X Updaters? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-1
The Customer’s Perspective: A Sample Session. . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-2
Chapter 18-Designing an Updater
Basic Components of an Updater . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-1
Handling Multiple Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-1
Designing Your Updater . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-2
Chapter 19-Building Updaters
How VISE X Updaters Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-1
Single File versus Application Bundle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-1
Building an Updater For a Single-File Application . . . . . . . . . . . . . . . . . . . . . . . . . 19-1
Creating an Updater Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-2
Modifying an Existing Updater Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-3
About the Updater Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-4
Adding Items. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-5
Adding Source Items to the Updater Item . . . . . . . . . . . . . . . . . . . . . . . . 19-5
Adding Target Items to the Updater Item . . . . . . . . . . . . . . . . . . . . . . . . 19-5
Removing Items from the Updater Item. . . . . . . . . . . . . . . . . . . . . . . . . . 19-5
The Updater Item Information Window. . . . . . . . . . . . . . . . . . . . . . . . . . 19-6
Identifying Resource and Data Fork Exceptions . . . . . . . . . . . . . . . . . . . . 19-6
Data Fork Exceptions for CFM Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-9
The cfrg Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-9
Identifying Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-10
Modifying Resource Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-11
Deleting a Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-11
Modifying Updater Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-11
Modifying File Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-12
Modifying Creation and Modification Date Options . . . . . . . . . . . . . . . 19-13
Building the Updater Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-13
Testing the Updater Item. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-14
Enabling Updater Items to Find Items to Update. . . . . . . . . . . . . . . . . . 19-14
Setting the Default Install Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-15
Setting Interface Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-15
Updater Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-16
Setting Auxiliary Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-19
Building an Updater for an Application Bundle . . . . . . . . . . . . . . . . . . . . . . . . . . 19-19
Creating a Bundle Updater . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-20
Modifying an Existing Bundle Updater . . . . . . . . . . . . . . . . . . . . . . . . . 19-21
VISE X User’s Guide
Contents–vii
About the Updater Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-22
Adding Items. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-22
Adding Source Items to the Bundle Updater . . . . . . . . . . . . . . . . . . . . . 19-23
Adding Target Items to the Bundle Updater. . . . . . . . . . . . . . . . . . . . . . 19-23
Removing Items from the Bundle Updater . . . . . . . . . . . . . . . . . . . . . . . 19-23
The Updater Item Information Window. . . . . . . . . . . . . . . . . . . . . . . . . 19-24
Building the Bundle Updater . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-24
Enabling Bundle Updaters to Find Items to Update. . . . . . . . . . . . . . . . 19-24
Modifying an Existing Updater Item . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-26
Accounting for Multiple Source Items . . . . . . . . . . . . . . . . . . . . . . . . . . 19-28
Setting the Default Install Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-30
Setting Interface Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-31
Updater Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-32
Setting Auxiliary Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-35
Section 4 Advanced Features
Chapter 20-Customizing the Archive Window
Archive Window Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-1
User-definable Archive Window Layouts . . . . . . . . . . . . . . . . . . . . . . . . . 20-1
Defining an Archive Window Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-3
Layout Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-4
Customizing the Layout Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-5
Layout Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-5
Archive Window Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-7
Chapter 21-Advanced Project Management
Build Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-1
Build Directive Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-3
Project Window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-6
Build Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-8
Build Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-9
Attributes tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-10
Directives tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-15
Post processing tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-15
Scripts tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-16
Dates tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-16
Active Build Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-18
Archive Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-19
Read Me Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-23
Viewing a Read Me File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-23
License Agreements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-23
Viewing a License Agreement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-23
Resource Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-24
Billboard Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-24
PlugIns/Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-26
VISE X and Source Control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-26
Chapter 22-Using Runtime Variables
Runtime Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-1
Using Variables for Text Substitution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-1
Declaring a Variable and Setting Initial Value . . . . . . . . . . . . . . . . . . . . . . 22-1
VISE X User’s Guide
Contents–viii
Entering Variables in Text Areas. . . . . . . . . . . . . . . . . . . .
Valid text areas for variable substitution . . . . . . . . . . . . . .
Special Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Variables for Install Logic . . . . . . . . . . . . . . . . . . . . . . . . . .
...
...
...
...
....
....
....
....
...
...
...
...
. . 22-2
. . 22-6
. . 22-7
. . 22-7
Chapter 23-Localization
Creating Installers in Different Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-1
MindVision Installer Language Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-1
Supported Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-2
About the Localization Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-2
Single-language Installers Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-3
Multi-language Installers Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-3
Single-Language vs. Multi-Language Installers . . . . . . . . . . . . . . . . . . . . . . 23-4
Installing Items with UTF-8 Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-4
Creating Single-Language Installers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-4
Create a Translator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-5
Enter Localization Information in the Translator XML File . . . . . . . . . . . 23-6
Create a Localization File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-8
Import Translator File Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-10
Select Installer Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-11
Select Language for Build Target(s). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-11
Creating Multi-Language Installers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-12
Create a Translator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-13
Enter Localization Information in Each Translator XML File . . . . . . . . . 23-14
Create a Localization File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-16
Import Multiple Translator File Resources . . . . . . . . . . . . . . . . . . . . . . . 23-18
Import Multiple VISE X Language Files . . . . . . . . . . . . . . . . . . . . . . . . . 23-19
Select Installer Default Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-21
Select Languages for Build Target(s) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-22
Select Mac OS X Options for Build Target(s) . . . . . . . . . . . . . . . . . . . . . 23-23
About Multi-Language Installers on Mac OS X . . . . . . . . . . . . . . . . . . . 23-23
Localizing the Installer Window Title . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-23
About Localized External Code in Localized Installers . . . . . . . . . . . . . . 23-24
Localized-at-Install Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-26
Overriding Dynamic Localization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-26
Language Codes for VISE X. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-27
Region Codes for VISE X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-28
Languages as Defined in Apple’s Script.h File. . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-29
User Defined Languages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-31
Chapter 24-Scripting VISE X with AppleScript
Scripting VISE X and Installers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-1
Including AppleScript Scripts Within an Installer . . . . . . . . . . . . . . . . . . . . . . . . . . 24-1
VISE X and AppleScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-3
Opening an Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-4
Saving an Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-4
Closing an Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-4
Bringing an Archive Up to Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-5
Setting the Validate Paths flag before Bringing an Archive Up To Date. . . 24-5
Setting the Assign Parent Package to New Files Flag. . . . . . . . . . . . . . . . . 24-5
Extracting an Archive Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-5
Setting Billboard Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-6
Setting the Current Build Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-6
VISE X User’s Guide
Contents–ix
Turning Build Directives On . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-6
Turning Build Directives Off . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-7
Turning Build Targets On . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-7
Turning Build Targets Off . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-7
Building an Install Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-8
Setting the value of an existing Variable . . . . . . . . . . . . . . . . . . . . . . . . . . 24-8
Editing an existing Download Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-8
Setting the Localization File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-9
Exporting a Translator File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-9
Importing a Translator File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-10
Validating an Update File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-10
Setting the Disk Sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-10
Removing Compressed Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-12
Exporting VCT Data as XML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-12
Creating a VCT from XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-13
Selecting an Archive Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-14
Setting Replace Options for the Selected Archive Item . . . . . . . . . . . . . . 24-15
Setting the Install Location for the Selected Archive Item. . . . . . . . . . . . 24-16
Deleting the Selected Archive Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-17
Creating an Updater Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-17
Opening the Updater Window for the Selected Updater Item. . . . . . . . . 24-18
Setting the Source for the Open Updater Window . . . . . . . . . . . . . . . . . 24-19
Setting the Target for the Open Updater Window . . . . . . . . . . . . . . . . . 24-19
Comparing Target and Source Files in the Open Updater Window . . . . 24-20
Adding a File or Folder to the Archive. . . . . . . . . . . . . . . . . . . . . . . . . . 24-20
Creating an Empty Folder in the Archive. . . . . . . . . . . . . . . . . . . . . . . . 24-21
Chapter 25-Controlling an Installer with AppleScript
Setting Easy Install. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-1
Setting Custom Install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-1
Selecting a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-2
Deselecting a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-2
Installing the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-2
Updating the Drive List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-2
Selecting the Install Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-2
Selecting a Hard Drive. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-2
Selecting a Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-3
Chapter 26-Creating External Code
General External Code Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-1
Types of Codes That Can Be Used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-1
When Codes Can Be Called . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-1
Resource IDs and Reference Constants . . . . . . . . . . . . . . . . . . . . . . . . . . 26-2
Using More Than One Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-2
Nonexistent or Misidentified Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-2
Automatically Copying Items to Installer Resources . . . . . . . . . . . . . . . . . 26-2
About the Samples Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-2
Where to Find More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-3
Creating External Code for VISE X Installers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-3
External Code Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-3
External Code Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-3
Setting VISE X Internal Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-16
Helpful Hints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-17
VISE X User’s Guide
Contents–x
Converting External Code Resources to CFPlugIns . . . . . . . . . . . . . . . . 26-19
Sending Information to Sub-launched Installers . . . . . . . . . . . . . . . . . . . . . . . . . . 26-19
Keeping a Debugger From Quitting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-20
Executing UNIX Scripts From the Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-21
Including Shell Scripts as Plain Text Files. . . . . . . . . . . . . . . . . . . . . . . . 26-22
Including Shell Scripts as Resource Files. . . . . . . . . . . . . . . . . . . . . . . . . 26-23
Chapter 27-VISE X Forms
VISE X Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-1
Sample Layout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-2
Creating a New Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-2
Configuring a Form Action to Display a Form . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-5
Form Editor Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-6
Undo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-6
Select All . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-6
Duplicate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-6
New Button. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-6
New Static Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-9
New Edit Text… . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-11
New Checkbox… . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-13
New Radio Button. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-14
New Radio Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-15
New Picture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-16
Expand Right . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-17
Reduce Right . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-17
Get Info… . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-17
Edit “Field Name”… . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-17
Set Tab Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-18
Save . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-18
Test… . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-18
Close. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-18
Item Order in Dialog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-18
Keyboard Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-19
Importing and Exporting Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-19
Chapter 28-On-Line Registration
Using Online Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-1
Create Registration Destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-2
Creating a Registration Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-4
Create Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-4
Include Online Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-9
Including Registration by Installer Settings . . . . . . . . . . . . . . . . . . . . . . . . 28-9
Including Registration by Form Action . . . . . . . . . . . . . . . . . . . . . . . . . 28-10
Registration Output Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-12
Custom Mailers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-13
Chapter 29-Install Locations
Install Locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Standard Install Locations . . . . . . . . . . . . . . . . . . . . . . . .
Additional Install Locations . . . . . . . . . . . . . . . . . . . . . . .
Setting Install Locations With Variables . . . . . . . . . . . . . . . . . . . . .
...
...
...
...
....
....
....
....
...
...
...
...
. . 29-1
. . 29-1
. . 29-2
. . 29-4
VISE X User’s Guide
Contents–xi
Chapter 30-Active Web Installers
Active Web Installers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-1
Active Web Installer Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-1
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-2
Designating Download Sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-11
Verify Files on Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-13
The User’s Initial Experience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-14
The User’s Subsequent Experiences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-17
Chapter 31-Working With VCT Data as XML
Exporting VCT Data as XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-1
Creating a VCT from XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-2
Section 5 Special Topics
Chapter 32-Extra Features
Encoding Files as BinHex, MacBinary or Tarball . . . . . . . . . . . . . . . . . . . . . . . . . . 32-1
Undoing or Redoing Mach-O Prebindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-2
Chapter 33-Shortcuts and Keyboard Commands
Archive Window Keyboard Shortcuts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Extended Add Dialog Keyboard Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . .
Drag and Drop Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Changing Multiple File Attributes Shortcuts . . . . . . . . . . . . . . . . . . . . . . . .
Index
VISE X User’s Guide
...
...
...
...
. . 33-1
. . 33-2
. . 33-2
. . 33-3
Contents–xii
VISE X User’s Guide
Section 1
Getting Started
1–1
Chapter 1
About VISE X
Why Use VISE X?
VISE X provides an easy-to-use graphical interface for building a master installation set for
CD-ROM or web delivery. The VISE X system maximizes the storage capacity of your
media and minimizes the necessary bandwidth by efficiently compressing the pieces of a
product.
Although custom code can easily be added to handle complicated situations, VISE X does
not require programming expertise for writing installation scripts. You can make gestalt
calls, evaluate the operating environment and check for existing files, sub-launch other
applications or VISE X installers, edit text files, execute UNIX scripts and much more,
without ever having to write custom external code! You can also display license agreements, splash screens, billboards and custom dialogs during an installation.
VISE X builds installers as universal binaries for use on both Intel-based and PowerPCbased Macintosh computers. The installers display a standard Mac OS X interface, including Aqua fonts and controls, Mac OS X property sheets and Installer background images
with transparency. They also support a number of popular media formats, so you can use
still images, movies, animation and sound to add impact to your installers.
To your customers, installing the software is as easy as reading the information that you
provide, and clicking the Install button.
About the
Compression Utility
The VISE X compression and decompression engine provides an extremely efficient means
of storing and retrieving data. Not only are disk space and bandwidth conserved, but in
many cases installations occur faster because the amount of data which must be read from
CD or web is reduced.
Localization
Features
VISE X supports localization of installers for several different languages. VISE X also contains a translator feature which lets you easily change file names, disk names, package
names and information, Easy Install text, Uninstall Text, and Action Item prompt text for
37 supported languages. Additionally, you can create a multi-language installer based on
the language of System in use on the customer’s computer.
About VISE X
VISE X was released in November 2003 as a new product from MindVision. While VISE X
builds upon the strengths of Installer VISE, it is a separate code base. Separating the code
base allowed us to focus VISE X functionality on Mac OS X. VISE X includes a number of
VISE X User’s Guide
Section 1 Getting Started
1–2
New Features in VISE X 5.0
new items written specifically for Mac OS X, and a great deal of legacy code written to
support System 6, System 7, Mac OS 8 and Mac OS 9 was removed.
New Features in
VISE X 5.0
With VISE X 5.0, the main updates were for Lion compatibility, and to make the builder a
Universal application. (The installers were already Universal applications.)
Lion Compatibility
We have tested this version of VISE X and verified its compatibility with Apple’s Mac OS
X v10.7 Lion.
Along with the compatibility testing, Gestalts in VISE X have been updated for Lion. You
can use the new “MacOS X 10.7 or Greater” Gestalt to ensure that install actions take
place only on the proper Mac OS versions.
There was no need to create additional search/install locations for Lion.
Intel-Native Builder
Application
The VISE X builder is now a Universal application, so it runs natively on either PowerPCor Intel-based Mac computers. As a result of this change, Rosetta is no longer needed for
running the builder on Intel machines.
For a list of changes in VISE X 5.0, see the Read Me document in the VISE X folder.
Information for
Installer VISE Users
Application File and
Folder Changes
Application file and folder changes from Installer VISE 8.x to VISE X include the following:
Creator/Type
Installer VISE 8.x
VISE X
Builder Creator
VIs5
VIsX
Builder Type
APPL
APPL
Archive Creator
VIs5
VIsX
Archive Type
VIS1
VISx
Installer Creator
VIS3
VISX
Installer Type
APPL
APPL
Segment2 Creator
VIS3
VISX
Segment2 Type
VIS4
VnSX
Table 1-1: Creator/Type Changes
Installer VISE 8.x
VISE X
Installer VISE Preferences
VISE X Preferences
Installer VISE Settings
VISE X Settings
Installer VISE Layouts (7.x)
VISE X Layouts
Table 1-2: File Name Changes
Chapter 1 About VISE X
VISE X User’s Guide
Information for Installer VISE Users
1–3
Installer VISE 8.x
VISE X
/viseversions/500/IVISE
/viseversions/VISE X
IVISE DebugWindow.TXT
VISE X DebugWindow.TXT
Table 1-2: File Name Changes
Product Comparison
For a comparison of the features offered by MindVision’s VISE X, Installer VISE and
FileStorm, see the following page on the MindVision web site:
http://www.mindvision.com/products_comparison.asp
Installer VISE 8.5
Conversion
For information on converting Installer VISE 8.5 projects to VISE X format, see the document “IVISE8.5_VCT_Conversion.pdf,” which is available for downloading at:
http://www.mindvision.com/downloads.asp
External Code Notes
If you created external code resources for use with Installer VISE, you will need to do the
following to make them compatible with VISE X:
Converting External Code
to CFPlugIns
■
For VISE X 3.0 and later versions, you will need to convert your external code
resources to universal binaries, in the form of CFPlugIns. See “Converting External Code to CFPlugIns” on page 1-3 for more information on that process.
When your CFPlugIns are ready, you should add them to your VCTs through the
“PlugsIns/Scripts” section of the Project window. Then bring up the Edit External Code dialog and use the “PlugIn/Shell Script (.bundle or text)” section to
declare the PlugIns and make them available for use by your installers. Finally,
specify when the installers should call the external code, using the same process
that you normally would.
■
For VISE X 2.0 and earlier versions, you will need to recompile your external
code resources before you add them to a VCT. Be sure to use the new header
files that are included with VISE X.
To enable the move to universal binary installers, MindVision has transitioned VISE X to
the Xcode environment. As a result, external code that you call from your installers (other
than AppleScripts and UNIX shell scripts) must be in the form of CFPlugIns. VISE X
includes a sample Xcode project that you can use to convert your existing external code to
CFPlugIns. The default location for the project is: VISE X/Samples/Sample Projects/
Installer External Code/Generic External Code.
To convert legacy external code to CFPlugIns:
1. From the Finder, open the source file for the external code that you want to convert. Later, you can copy code from this file and paste it into the new source file.
2. Within the Generic External Code folder, double-click EC_PlugIn.xcodeproj to
open the Xcode project. (Xcode is required.)
3. Select the PlugIn.c source file for editing.
4. Replace code in PlugIn.c with your own as needed. You will probably need to make
your replacements within the code that begins with the comment “YOUR CUSTOM CODE STARTS HERE.” Do not modify the code that begins with the comment “OUR REQUIRED CODE STARTS HERE - PLEASE DO NOT MODIFY.”
5. Build the CFPlugIn. (All Xcode build settings should already be correct for the purposes of this project, including building as a universal binary.) The new CFPlugIn
will be located in the Output folder.
VISE X User’s Guide
Section 1 Getting Started
1–4
Chapter 1 About VISE X
Information for Installer VISE Users
VISE X User’s Guide
2–1
Chapter 2
Getting Started with VISE X
This chapter contains information and instructions for installing VISE X on your system.
System
Requirements
The system requirements are as follows:
■
Builder application — Mac OS X v10.4 or greater
■
Installers — Mac OS X v10.2 or greater
Also note the following items in regard to the builder application:
■
Contents of the
Installation
When running the builder on a PowerBook, the “Font smoothing” Appearance
option must be set to “Turn off text smoothing for font sizes 8 and smaller” in
order for dialogs to display properly. If the option is set for font sizes larger than
8, headings and controls overlap.
The following Easy Install packages are contained in the VISE X installer:
Package
Contents
Application and
Read Me
The VISE X application and a Read Me file.
User’s Guide
The VISE X User’s Guide in Adobe Acrobat Reader format
(.pdf).
Additional Install
Locations
A folder of location definition files that you can use to extend
the options that are available in the builder application’s “Install
To” and “Search Location” popmenus. For more information,
see “Additional Install Locations” on page 29-2.
Samples
A folder of sample VCTs and sample external code, complete
with source code so that you can adapt the examples to suit
your needs.
Table 2-1: VISE X Installation Packages
VISE X User’s Guide
Section 1 Getting Started
2–2
Installing VISE X
Installing VISE X
To begin installation of VISE X, follow these steps:
1. Double-click the VISE X installer icon. A Read Me file will be displayed. This file
will be included in the installation folder when you install VISE X.
2. If you wish to print the Read Me file, click Print. If you wish to save the file to a
location of your choice, click Save.
3. To continue installation, click Continue or press <Return>. The license agreement
for VISE X will be displayed.
4. If you wish to print the license file, click Print. If you wish to save the file to a
location of your choice, click Save.
5. Click Continue or press <Return>. A dialog will prompt you to agree to the terms
of the software license agreement.
6. If you do not accept the terms of the license, click Disagree to cancel the installation. Otherwise, if you accept the terms of the license, click Agree.
Choosing a Destination
for the Install
The VISE X installer will display all the volumes available on your machine for installing
VISE X. Make your selection and then click Continue or press <Return>.
Illustration 2-1: Selecting a Destination
Choosing Easy Install or VISE X can be installed to your hard disk using either the Easy Install or Custom Install
options. The Easy Install option, which is the default, will install all files to the location of
Custom Install
your choice. If you wish to install all the files, click Continue or press <Return> to begin
the installation. (You may skip to “Completing the Installation” on page 2-3.)
The Custom Install option allows you to install only the parts of the VISE X software
package that you choose. You can choose as many packages in the Custom Install option
as you wish.
To choose the packages you wish to install, follow these steps:
1. Choose Custom Install from the popmenu provided in the Easy Install window.
Chapter 2 Getting Started with VISE X
VISE X User’s Guide
Registering VISE X
2–3
2. Select the desired packages and then click Continue or press <Return> to begin
the installation.
Illustration 2-2: VISE X Custom Install Packages
Completing the
Installation
An installer log file containing information about the installation will be created at the
root of the install folder.
About the VISE X
Extensions and VISE X
Locations Folders
When you install the VISE X application, the VISE X Extensions folder and the VISE X
Locations folder will be included in the application’s resources. These two folders must
remain in their default locations to ensure that the program functions correctly.
Registering VISE X
If you create an installer with an unregistered copy of VISE X, the installer will:
■
Display the VISE X splash screen to the customer before your splash screen, alerting them that you used unlicensed software; and
■
Expire three days from the date that the unlicensed installer was built.
If your copy of VISE X is registered, then the VISE X splash screen will never be visible to
the user, and the installer will not automatically expire.
To register your copy of VISE X:
1. From the File menu, select Register...
VISE X User’s Guide
Section 1 Getting Started
2–4
VISE X Version Checking
2. The following dialog appears:
Illustration 2-3: VISE X Registration dialog
3. Enter your name or the name of your company.
4. Enter the serial number of your copy of VISE X.
5. Click Register.
If you do not register your copy of VISE X now, you’ll be asked to register each time you
build an installer.
VISE X Version
Checking
If you have Internet access from your computer, you can quickly check to see if you are
using the most current version of VISE X. MindVision is constantly working to improve
our product and add new features. As a result, we release a newer version several times
each year.
To check the MindVision Server for the newest version of VISE X:
1. Select the Query MindVision Server command from the Extras menu.
2. VISE X will attempt to establish an Internet connection with our server and compare your version of VISE X with the newest version available.
3. If you are not using the latest version, you may always obtain it directly from our
World Wide Web site at <http://www.mindvision.com>. If you do not have an
Internet connection, you can call our support line at (402)323-6600 to check for
the latest version.
Chapter 2 Getting Started with VISE X
VISE X User’s Guide
Section 2
Building Installers
3–1
Chapter 3
Creating an Archive
About Archives
An archive is the building block of any installer you create. In an archive, you:
■
Identify all the files that are part of the installation set.
■
Set options for each file (if appropriate), such as where they should be installed.
■
Assign files to different installation packages.
■
Set general preferences for the way that files are displayed to you.
Creating and adding files to an archive is always the first step in building your installer.
If you choose, the files you place in an archive can maintain their Finder appearance after
the customer installs them. For example, if the files are arranged in View by Icon, the customer who installs the files will see them set up in the same way that they were arranged
on the computer you used to create the archive.
To maintain Finder icon positioning, you will need to note the following:
VISE X User’s Guide
■
In the archive’s Installer Settings, Advanced tab, the setting Ignore DS Store
Files should be turned off. See “Adding Files to an Existing Archive” on
page 10-27 for more information on this setting.
■
VISE X will honor .DS_Store file settings (thereby maintaining icon positions) if
that hidden file is present in a folder you add to your archive. You can view
.DS_Store files if present by opening the folder in the main archive window.
■
If you make changes to a folder’s icon positioning at the Finder level, the best
way to ensure that the Finder updates the folder’s .DS_Store file is to log out and
then back in to Mac OS X. You can then add the folder to the archive, or if it’s
already present, you can perform a Bring Up To Date operation. See “Bringing
the Archive Up-To-Date” on page 3-7.
Section 2 Building an Installer
3–2
Creating a New
Archive
Creating a New Archive
To create a new archive:
1. After launching VISE X, select New Archive…from the File menu.
2. After saving, a blank archive window similar to the one below will be displayed.
Illustration 3-1: Archive Window for new archive
3. Click the Add button at the upper left corner of the archive window. The Standard
Add dialog box will be displayed, allowing you to select files to include in the
archive.
The Extended Add
Dialog Box
When you begin adding files to an archive, a dialog box similar to the one following is displayed.
Illustration 3-2: Standard Add Dialog
Chapter 3 Creating an Archive
VISE X User’s Guide
Adding Files to the Archive
3–3
VISE X preferences are set to display the Standard Add Dialog Box by default. If you wish
to use the Extended Add Dialog Box, which has more features and options, press the
Option key on the keyboard while clicking the Add button in the archive window or
change the setting in Preferences. (For information about changing preferences, see “Modifying Archive Preferences” on page 3-5.)
The Extended Add Dialog appears below. (In this example, several files have already been
selected). The list of files in the dialog box reflects the file and directory structure of your
hard drive.
Illustration 3-3: Extended Add Dialog Box
By default, items are displayed alphabetically by name. To find a file quickly, type the first
few letters of its name.
Displaying Items
To display the contents of a folder, click the triangle to the left of the folder. The contents
will be displayed beneath it.
To display the contents of another drive, hold down the mouse over the name of the current drive (at the top right corner of the window) and select the desired volume from the
popmenu.
Selecting Items
Files and folders are added to the archive by selecting them. To select an item, click in the
box to the left of its name, or anywhere on the line where its name appears. When an item
has been selected, an “x” is displayed in the check box and the name of the item appears
in boldface type.
To deselect an item, click the line where its name appears or click the check box to
remove the “x” and the boldface type.
Shortcuts
For complete information about shortcuts for navigation and file selection, see “Extended
Add Dialog Keyboard Shortcuts” on page 33-2.
Adding Files to the
Archive
To add files to the archive:
1. Click the mouse on the line containing the name of the file you wish to select. If
you select a folder, the entire contents of the folder will be selected. You may select
as many files as you wish. If you wish to deselect a file, click its name again.
2. When you’ve selected all the files you wish to add to the archive, click Add.
VISE X User’s Guide
Section 2 Building an Installer
3–4
Creating an Installation Folder
3. If there are no more files to add to the archive, click Done. The Add dialog box
will be removed and the archive window will be displayed, containing the files that
you selected.
You may also drag files directly from the Finder into the archive.
If you’re making last-minute changes to an existing archive and are adding or replacing
only a few files, you might wish to use the Bring Up To Date feature. For a complete discussion of Bring Up To Date, see Chapter 16-Maintaining Archives.
Creating an
Installation Folder
Sometimes the items in your archive are from several different locations on your computer
and on your local network, so there isn’t a single folder at the root of the archive containing all of the files. VISE X can create an “installation folder” that will be created on the
customer’s system and store all the materials that get installed.
To create an “installation folder”:
1. Select Installer Settings... from the Archive menu, and click on the Behavior tab.
2. Click on the Create Installation Folder Named checkbox.
3. Type in the name of the folder you wish to have created during the install.
Illustration 3-4: Create Installation Folder
When the installer is run, all the items that are installed will be placed in a folder
with the same name that you entered.
Catalog Only
Special Information for CD-ROM Installers
If desired, you may set up your archive so that only a catalog of files is stored in the
archive. This saves the time of compressing the files into the archive and decompressing
them for the installer. However, this feature requires that you select Only Store Catalog
of Files in Advanced Settings before you save your archive.
For information on using this feature, see “Only Store Catalog of Files” on page 10-26.
Saving an Archive
After adding the files you wish to include in your installation to the archive, you should
save the archive.
To save the archive:
1. From the File menu, select Save.
2. VISE X will compress the files into an archive, which may take a few moments,
depending on the size of the archive and the speed of your computer.
Chapter 3 Creating an Archive
VISE X User’s Guide
Changing File Names in the Archive
Changing File
Names in the
Archive
3–5
If desired, you may change the names of files and folders within the archive. Although this
will not affect the source files that you used to create the archive, any installation of those
files from the archive will contain the new name.
Changing file name in the archive is similar to changing it at the Finder.
To change the name of a file:
1. At the archive window, click the name of the file you wish to change. An editing
box will appear around the file’s name, and the name will be highlighted.
2. Change the name as desired.
3. Save the modified archive.
Removing Files from
the Archive
To remove a file from the archive:
1. Select the file or files you wish to delete.
2. Click the Delete button in the archive window. The file will be deleted. (If you
wish to be warned before a file is deleted from the archive, change the “Confirm
Before Deleting Files” preference setting as described below.)
3. Save the modified archive.
Modifying Archive
Preferences
To change preferences:
1. In the VISE X menu, select Preferences...
Illustration 3-5: Archive Preferences
2. Change preferences as desired.
3. Click OK.
VISE X User’s Guide
Section 2 Building an Installer
3–6
Verifying and Updating an Archive
Changes to the preferences file affect the application, not just the
archive that you’re creating. Any changes that you make to the Preferences will remain in effect for this archive and any other archives
that you work with unless you change the Preferences file again.
You can change many features of how archives are handled by changing VISE X’s preferences.
Item
Purpose when selected
Default
Display Invisible Files
in Add Dialog Box
Invisible files (such as the Icon file in a
folder) are listed in Add dialog box.
Selected
Archive Original
Instead of Alias
Allows you to archive original file even
when you select the file's alias.
Not Selected
Use Extended Add
File Dialog Box
Allows more options when selecting files
for an archive
Not Selected
Confirm Before
Deleting Files
Prompts you to confirm whether files
should be deleted
Selected
Confirm before
Saving Get Info or
Action Item Changes
When changes are made to a file’s or action
item’s options in the item’s Info window,
confirms changes before saving.
Selected
Check for Duplicate
Names when Adding
New Files
Alerts you that two files of the same name
are in a sub-directory. If selected, allows
you to replace the file or skip replacing if
desired. If not selected, you may add as
many files of the same name as you wish.
NOTE: This feature is only functional if
you add files at the Extended or regular
Add File dialog; Check for Duplicate does
not apply to files added using Drag and
Drop.
Selected
Table 3-1: Archive Preferences
Verifying and
Updating an Archive
The verify command performs a number of checks including one which makes sure the
compressed files in an archive are valid and have not become corrupt. (This feature is useful when recovering archives after a system or a hard drive crash.)
The steps below describe a simple verification and update procedure. If you are updating
an archive to include new or changed files, see Chapter 16-Maintaining Archives.
Verifying the Archive
To verify an archive, select Verify Archive from the Extras menu. If you receive an error
message, you should bring the archive up to date.
Chapter 3 Creating an Archive
VISE X User’s Guide
Verifying and Updating an Archive
3–7
Bringing the Archive Up- To update all files in an archive:
To-Date
1. From the Archive menu, select Bring Up To Date. An Update window will be displayed.
2. Locate and select the source folder for the archive.
3. Select all items that should be part of the archive.
4. Click Update.
The archive will be recreated from the original files, and retain the settings for the files
from your original archive.
If you moved the positions of the icons at the Finder level for the files in the source
folder, you can update that information quickly using the Bring Up To Date feature. If the
only thing that’s changed for an item is the position of its icon, its checkbox will not be
selected, though its status will be <FInfo Changed>.
VISE X User’s Guide
Section 2 Building an Installer
3–8
Chapter 3 Creating an Archive
Verifying and Updating an Archive
VISE X User’s Guide
4–1
Chapter 4
Creating Packages And Assigning Files
About Packages
Packages are groups of files to be installed together that you specify when you create an
installer. The customer who installs the program chooses from the list of package names
to customize the installation process.
For example, you might create an Application package, a Demo package, and an Additional Tools package. When customers run your installer, they can use the Easy Install
option to install all the materials, or they can use the Custom Install option to install only
the packages that meet their needs. (If no additional package names are entered, the Custom Install option will not be available.)
Every archive created with VISE X contains one package by default: the Easy Install Package, which normally contains every item in the archive. The Easy Install Package will be
installed if the customer chooses the Easy Install option when the installer is run. (If
desired, you may disable the Easy Install option so that customers must choose which
packages to install.)
When you create packages, you can:
VISE X User’s Guide
■
Add informational text to each package or sub-package to aid the customer
choosing what to install.
■
Create “sub-packages,” which are packages that are components of a larger package (also known as hierarchical packages). If customers chose to install a package
that contains sub-packages, they may select any of the sub-packages associated
with it.
■
Create “list packages,” which contain several files from which the customer may
choose as many individual files as desired.
■
Assign a custom icon to each package.
■
Create mutually exclusive groups of packages, in which the customer may only
install one of the packages in the group.
■
Assign Gestalts to packages to determine whether or not they are displayed to
the customer as part of the installation.
Section 2 Building an Installer
4–2
About Sub-Packages
VISE X allows you to create up to a total of 255 packages of any kind. The total includes
the Easy Install package as well as any other packages, including sub-packages and list
packages that you create.
An archive report can list any package that you create which does not have files assigned
to it. This information will also be displayed if you start to build an installer in which
you’ve defined packages that don’t contain any files.
About Sub-Packages
In addition to creating packages, you may also create sub-packages. Sub-packages are packages that are a part of another package. If the customer chooses to install a package that
contains sub-packages, he may also choose which of the associated sub-packages should
also be installed.
For example, if your product includes different sets of sample files, you can set up your
installer to include a single package called “Samples,” from which the customer can
choose the desired samples (such as “Word Processing Samples,” “Spreadsheet Samples,”
or “Database Samples.”)
Illustration 4-1: Sub-packages displayed in Package List
If the customer chooses Custom Install, the Samples package will be displayed with an
expandable arrow, indicating a set of sub-packages from which you can choose. The fol-
Chapter 4 Creating Packages And Assigning Files
VISE X User’s Guide
Package Dependencies
4–3
lowing illustration shows an installer in which the customer has displayed the sub-package
contents of the “Samples” package:
Illustration 4-2: Installer with sub-packages displayed
Package
Dependencies
Package dependencies can be used to tie packages together so that when one package is
selected another is automatically selected or when one package is deselected another package is automatically deselected.
To set up package dependencies:
1. From the Archive menu select Packages… The Package List will be displayed. The
Dependencies button is not enabled until more than one package is defined.
Illustration 4-3: Package List
VISE X User’s Guide
Section 2 Building an Installer
4–4
Package Dependencies
2. Define the packages for your installer.
3. When you have defined all packages you are now ready to assign dependencies.
Click the Dependencies… button in the Package List window.
Illustration 4-4: Package List Dependencies button
4. In the Package Dependencies dialog select from the Package popmenu the package
upon which other packages will be dependent.
The Package popmenu at the top of the Package Dependencies dialog displays the
current package for which dependencies will be set. It is automatically set to the
package you have selected in the Package List dialog, but you can change it to
other packages at any time. The current package is disabled in the lists since you
cannot set dependencies for itself.
In the example that follows, we have an application which has on-line help available in two formats, PDF and HTML. First, we will set dependencies for the
Chapter 4 Creating Packages And Assigning Files
VISE X User’s Guide
Package Dependencies
4–5
Help.pdf package.
Illustration 4-5: Package Selection in Package Dependencies
The list on the left contains the packages that you wish to turn on/off when the
current package is turned ON. The list on the right contains packages that you
wish to turn on/off when the current package is turned OFF.
The Clear button clears all dependencies for the current package.
The Clear All button clears all dependencies for every package.
In the installer, these dependencies come into effect in the Custom Install window
when the user clicks on and off packages. Simple logic is used when turning on and
off dependent packages so that packages will follow normal default behavior. If you
turn on a dependent package that is a parent hierarchical package, it will automatically turn on all of its child packages. If you try to turn on multiple mutually exclusive packages, only the last one will be turned on.
When a user clicks on a sub-package to turn it on, it will automatically turn on all its dependent packages. However, if instead the user
clicks on a package which automatically turns on this same sub-package, the dependencies of the sub-package will not be in effect.
Package Dependencies are ignored when using the Select and Deselect AppleScript commands to check and uncheck package checkboxes in a built installer. For more information on the Select and
Deselect AppleScript commands, see Chapter 25-Controlling an
Installer with AppleScript.
VISE X User’s Guide
Section 2 Building an Installer
4–6
Package Dependencies
5. Based upon the settings we have made in the example below, when the Help.pdf
package is selected at installer runtime the Help Reader for PDF will automatically
be checked on and the HTML help components will automatically be checked off.
Illustration 4-6: Setup for Help.pdf package
6. When dependencies for one package have been completed, select a different package from the Package popmenu to set up dependencies for that package. In our
example, we have switched the Packages popmenu to the Help.html package. Based
upon the settings we have made in the example below, when the Help.html package is selected at installer runtime, the Help Reader for HTML will automatically be
checked on and the PDF help components will automatically be checked off.
Illustration 4-7: Setup for Help.html
Chapter 4 Creating Packages And Assigning Files
VISE X User’s Guide
List Packages
List Packages
4–7
If you wish to allow customers to choose among several different files to install, you may
create a list package, which presents the files as a list from which any or all of the files may
be selected.
For example, if your installation includes a large set of items, such as several PostScript
Printer Define files, it’s likely that customers will only want to install the files that are relevant to their needs. By placing those files in a list package, customers may select which of
the files they wish to install.
You may add custom header, footer and help text to assist the customer in making a decision. The list from which the customer selects will appear like this:
Illustration 4-8: Installer with list packages displayed
You can also attach a PICT containing help information about the list package.
Creating a Package
To create a package:
1. From the Archive menu, select Packages... The Packages List window will be displayed.
2. Click the New Package button. The Edit Package dialog box will be displayed.
3. Enter information in the appropriate fields. For more information about the kinds
of information you an enter in the Edit Package dialog box, see the following section, “Edit Package options” on page 4-8.
4. Click OK to return to the list of packages.
VISE X User’s Guide
Section 2 Building an Installer
4–8
Edit Package options
Creating a Package
The following is a sample Edit Package dialog box:
Illustration 4-9: Edit Package dialog box
The following items are available from within the Edit Package dialog:
Name
Description
Name
The name of the package that will be visible to the customer.
Package names may have up to 63 characters.
Description
A text description of the package that will be visible to the
customer after clicking the Information button. The Description
field can contain up to 255 characters. If you do not enter text
in this field, the default text “This option installs the <Package
Name> package” will be displayed, with the name of the package
in the blank.
Pad (Bytes)
Allows you to specify additional disk space that the installer
should allocate for this package. If you enter a pad figure, the
installer will add that amount to the actual disk space required
by the package contents.
Table 4-1: Edit Package Options (Sheet 1 of 3)
Chapter 4 Creating Packages And Assigning Files
VISE X User’s Guide
Creating a Package
4–9
Name
Description
Version
The version number that you assign to your software. The
Version field can contain up to 9 characters.
If you enter the unique ID of a file in the archive, at installer
runtime the version field will be filled with the version of the
file designated by #uniqueID#. The unique ID of a file is
available in its Get Info window. When entering a unique ID it
must be entered as #uniqueID#.
User Flag
Special field available to developers for identifying a package
through external code.
Icon ID
The resource ID number of the custom icon, if one is assigned.
Choose Icon...
Allows you to assign a custom icon to the package. This icon is
visible to the customer after clicking the Information button for
that package. The Icon ID field contains the resource ID of the
icon. If you choose not to assign a custom icon, then the
package will display VISE X’s default icon for packages. For
more information on adding a custom icon to a package, see
“Adding an Icon to a Package” on page 4-21.
Separator
Used to create a separator line that you can move around in the
packages list to create a visual barrier between packages. If you
create a package as a separator, no other information can be
entered in the window for that package.
Mutual Exclusive
Group
Selecting Separator enables the Mutual Exclusive Group option.
Selecting Mutual Exclusive Group for a separator means that
only one of the packages that appears between the separator
lines may be installed. For more information, see “Creating
Package Separators and Mutual Exclusive Groups” on page 4-10.
Show in Install
PopMenu
The package name will be one of the options available in the
popmenu displayed for the Installation Type screen of the
installer. If a package is set to show in install popmenu, it will
not be listed for Custom Install.
Restart after
Installing
Forces the customer to quit all open applications before
beginning the installation, and allows the customer to restart the
computer after installing the package. See also “Restarting After
Installation” on page 4-10.
NOTE: Shutting down applications as described above is
conditional based on the “Shutdown Applications Before
Installing” option on the Behavior tab of Installer Settings. If
this package option is enabled but the Installer Settings option
is not, the installer will install the corresponding package
without shutting down applications first. See also “Designing
the Installer’s Behavior” on page 10-18.
Default Package
On
When checked, the package will be selected by default when
shown in the Custom Install list. The user can override the
default.
Table 4-1: Edit Package Options (Sheet 2 of 3)
VISE X User’s Guide
Section 2 Building an Installer
4–10
Creating a Package
Name
Description
List Package
Creates a package whose contents will be displayed to the
customer in the form of a list. The customer may select any or
all of the items in a list package. (For more information about
list packages, see “Creating a List Package” on page 4-12.)
Must Select at
Least One
Requires the customer to select at least one item in the list
package.
Can Select More
Than One
Allows the customer to select more than one item in the list
package.
List Header and
List Footer
These fields let you enter explanatory text that appears above
and below the list of files in a List Package.
List Help
Assigns a Help PICT to the list package. The customer can view
the PICT by clicking a Help button at the dialog box for the list
package. For more information, see “Assigning a Help PICT to a
List Package” on page 4-14.
Gestalt
Adds a gestalt call to the package. If the conditions of the gestalt
are met on the customer’s system, then the package will be
available for installation; if the conditions of the gestalt are not
met, the package can not be installed by the customer.
Build Directives
Allows Build Directives to be assigned to packages. When the
installer is built, packages which do not meet the build directives
are not included in the installer. (For more information about
package build directives, see “Package Build Directives” on
page 4-17.)
Table 4-1: Edit Package Options (Sheet 3 of 3)
Creating Package
Separators and Mutual
Exclusive Groups
Separators are used to create a visual barrier between sets of packages in the list. A mutually exclusive group separator means that the customer will only be able to install a single
package from the selection of packages that appears between the separator lines. (Information about arranging the order and location of packages can be found later in this section,
in “Rearranging the List of Packages” on page 4-22.)
To create a separator:
1. Create a new package.
2. Place a check in the box next to Separator.
3. If you wish to create a mutually exclusive separator, click Mutual Exclusive
Group.
You don’t need to enter any more information in the Edit Package window, as any
text you enter will be discarded.
4. Click OK.
Restarting After
Installation
If you want the customer to have the option to restart the computer after the installation
of this package, select Restart After Installing. (For information on how this item can also
affect the shutting down of applications, see “Restart after Installing” on page 4-9.)
Chapter 4 Creating Packages And Assigning Files
VISE X User’s Guide
Creating a Package
4–11
In conjunction with other factors, the selection of this item for a package determines
whether a restart will be suggested or forced after the installation of the package. (Other
factors include the installation options of files, and the options chosen at the Installer Settings window.)
After-Install Restarts
The following conditions determine whether a restart should occur at the end of the
installation process.
■
The Restart After Installing item in the Edit Package window has been
selected, and that package is being installed by the user; or
■
The Restart After Installing item in the Get Info window has been selected,
and that file or folder is being installed by the user; or
■
An active, non-deletable file such as QuickTime is being replaced; or
■
Resources are being written into the active System file.
This chart displays the circumstances where meeting one of the above conditions will suggest or force a restart
Force Restart Where Appropriate is selected
in Installer Settings/Behavior Tab
Then restart is...
Not Selected
Suggested
Selected
Forced
Table 4-2: After-Install Restarts
Creating a Sub-Package Sub-packages are complete packages of files which are part of another package.
To create a sub-package:
1. Create the package as described in the rest of the section.
2. Close the Edit Package window and save changes.
3. In the Package List window, arrange the packages vertically such that the package
which is going to become a sub-package is below the parent package.
VISE X User’s Guide
Section 2 Building an Installer
4–12
Creating a Package
4. Select the name of the package you wish to designate as a sub-package and click the
right arrow below the package list.
Illustration 4-10: Creating a sub-package
The sub-package that you created will appear indented.
A sub-package is associated with the first regular package above it in
the Packages window. To change the package that a sub-package is
associated with, rearrange the items in the Packages window. For
information about rearranging packages, see “Rearranging the List of
Packages” on page 4-22.
Creating a List Package List packages are packages from which the customer may select individual files for installation. The list displays all files that are associated with that package, allowing the customer
to select the individual files they wish to install.
To create a list package:
1. Create the package as described in the rest of the section.
Chapter 4 Creating Packages And Assigning Files
VISE X User’s Guide
Creating a Package
4–13
2. Select List Package.
Illustration 4-11: Setting up a package as a list package
3. To require the customer to select at least one item from the list package, click Must
Select At Least One.
4. To allow the customer to select more than one item from the list package, select
Can Select More Than One.
Attaching Header and
Footer Text
You may enter text that will appear above and below the list of items from which the customer can choose. You are limited to 255 characters in each field.
To enter list header and footer text:
1. In the List Header field, enter the text that you wish to appear above the list.
2. In the List Footer field, enter the text that you wish to appear below the list.
When your customer clicks the Install button in your installer, a List dialog
appears. The text you entered in the Header and Footer fields is displayed as in the
VISE X User’s Guide
Section 2 Building an Installer
4–14
Creating a Package
example below:
Illustration 4-12: List package with header and footer text
You may wish to attach header and footer text or the Help PICT feature to the list of items (described below) to inform your customers
that they can select discontinuous items by holding down the Command key on the keyboard while clicking the mouse.
Assigning a Help PICT to a If you wish to provide your customers with more information than you can place in the
List Header and List Footer, you may attach a PICT containing additional information for
List Package
the package. If the customer clicks the Help button at the dialog box for the list package,
the PICT will be displayed.
To attach a Help PICT to a list package:
1. At the application used to create the Help PICT, copy the Help PICT to the Clipboard.
2. Click List Help. The Edit List Package Help window will be displayed.
3. In the Edit List Package Help window, select Black and White if the picture is 1bit, or Color if the picture is 8-bit.
4. Press Command-V to paste the screen into the window. Although the image
appears scaled within the dialog box, it will appear correctly to the customer.
To remove a Help PICT, click Remove or paste a new screen into the window.
Assigning a Gestalt to
the Package
You may assign a gestalt call to a package. If the conditions of the gestalt are met on the
customer’s system, then the package will be displayed as part of the software being
installed in the Easy Install window, and that package will be available for the customer to
choose on the Custom Install window.
For example, if you have a package containing QuickTime movie files, you can assign the
Has QuickTime 6.0 or Greater gestalt to the package. If the customer is using QuickTime
Chapter 4 Creating Packages And Assigning Files
VISE X User’s Guide
Creating a Package
4–15
6.0 or greater, then the package will be part of the regular installation. If the customer is
not using QuickTime 6.0 or greater, the package will not be part of the Easy Install and
will not be visible in Custom Install.
Assigning a gestalt call to a package in this way will only determine
whether the package is visible in the Easy Install list of packages and
the Custom Install list of packages. To ensure that individual files are
only installed under certain circumstances, you must also either a)
attach gestalts to each file or b) ensure that each package containing
the files has a gestalt attached to it.
To assign a gestalt to the package, hold down the mouse over the Gestalt popmenu and
select the desired gestalt(s) from the list.
Language and Region
Gestalts for Packages
VISE X has built in gestalt selectors which enable packages to be displayed only for specific Languages or Regions.
To create a Language or Region Gestalt for Packages:
1. Select Gestalts… from the Archive menu.
2. Click the New button in the Gestalt List.
Illustration 4-13: Gestalt List
VISE X User’s Guide
Section 2 Building an Installer
4–16
Creating a Package
3. In the Edit Gestalt dialog enter a name, selector and value for this new gestalt
check.
Illustration 4-14: Edit Gestalt
Option
Description
Selector
Region = InRg
Language = InLg
Value
For Region values, see “Region Codes for VISE X” on
page 23-28.
For Language Codes, see “Language Codes for VISE X” on
page 23-27.
Table 4-3: Special Setup for Region and Language Gestalts
Chapter 4 Creating Packages And Assigning Files
VISE X User’s Guide
Creating a Package
4–17
4. In the Edit Package window of a package which should only be available in a specific region (in this case, Germany), select the newly created gestalt from the Gestalt
popmenu.
Illustration 4-15: Selecting a Package Gestalt
When the installer is executed on a user’s machine, if the gestalt check for Germany
returns false, this package will not be available for install. The installer determines
which language and region the user is in by accessing information provided by the
operating system that the user is running.
Package Build
Directives
Package Build Directives enable the exclusion or inclusion of packages in an installer at
installer built time. When the installer is built, packages which do not meet the build
directives are not included in the installer.
For more information on setting up build directives, see “Build Directives” on page 21-1.
To assign a build directive to a package:
1. Set up Build Directives by selecting Build Directives… from the Archive menu.
VISE X User’s Guide
Section 2 Building an Installer
4–18
Creating a Package
2. In the Build Directives dialog, enter your build directive names and check one or
more as the active build directive(s).
Illustration 4-16: Build Directives setup
3. Click OK to close the Build Directive dialog.
4. From the Archive menu select Packages…
5. From the Package List, define the packages that will be in all installer builds from
this VCT.
6. To limit the inclusion of a package to specific installer build, select the package in
the Package List, and click the Edit button.
Illustration 4-17: Package List with Package Selected for Edit
Chapter 4 Creating Packages And Assigning Files
VISE X User’s Guide
Creating a Package
4–19
7. Assign this package to one or more build directives by selecting items from the
Build Directives popmenu.
Illustration 4-18: Selecting Build Directive for a Package
VISE X User’s Guide
Section 2 Building an Installer
4–20
Creating a Package
8. In the Archive window, if packages are being displayed in the current layout, the
package titles are grayed if they do not match the build directives.
Illustration 4-19: Archive Window with Disabled Packages
Package Build Directive
Guidelines
Build Directives serve as limiting agents for packages. If no build directives are checked,
the inclusion of the package in an installer build will not be limited. Another way to say
the same thing would be that if no items are checked in the Build Directive popmenu, this
package will always be included when an installer is built.
Illustration 4-20: Setting Build Directives
The Build Directives popmenu will display any build directive that has been set up in the
Build Directive window as well as the Any Match item.
If only one build directive item is checked, as in the example below, this package will be
included in the built installer only when that build directive is in effect.
Chapter 4 Creating Packages And Assigning Files
VISE X User’s Guide
Creating a Package
4–21
Checking multiple items in the Build Directive popmenu will result in an AND condition.
In the example below, this package will be included in the installer when the Debug Build
AND the English Release build directives are in effect.
The Any Match item causes an OR condition to be in effect for any other checked items.
In the example below, this package will be included in the installer when Debug Build OR
English Release is in effect.
If Any Match is the only item checked in the Build Directive popmenu, this package will
never be included when an installer is built.
If no items are checked in the Build Directive popmenu, this package will always be
included when an installer is built.
Files must have build directives set also if you do not wish to have
them included in the an installer. Because a package is not included
in an installer does not mean that any associated files are not
included also.
Hierarchical sub-packages and package build directives - If a
parent package does not meet the build directives then any of its
children packages will also be disabled, regardless of their build directive setting.
Adding an Icon to a
Package
Packages which do not have custom icons assigned to them will be listed in a diagnostic
report (for more information, see Chapter 12-Generating Archive Reports); if you choose
not to assign a custom icon, then the package will display VISE X’s default icon for packages. Icons attached to packages are visible when the installing customer clicks the Information button for the package in the installer.
Supported icons include .icns files and color icons copied from files and folders.
You can add an icon in three ways: by locating the item at the Finder from within VISE X
using the Choose Icon... button; by copying and pasting the icon from a file’s Get Info
window at the Finder; or by copying the icon for an item in the archive from that item’s
Get Info window in VISE X.
VISE X User’s Guide
Section 2 Building an Installer
4–22
Rearranging the List of Packages
To locate an icon at the Finder from within VISE X:
1. From the Edit Package dialog box, click Choose Icon...
If you have just created the archive, a window containing the icons for all the files
in the archive will be displayed. If you have closed and reopened the archive, the
icons for the files in the archive will no longer be visible.
2. If the icon you wish to assign to the package is displayed, click the icon. Then skip
to step 4.
3. If no icons are displayed, or if you wish to assign an icon which is not assigned to
an application in the package, click Add File... to display a standard file dialog
box, and locate the .icns file or the application with the desired icon.
When locating a file through the Add File... option, if you want the archive to
temporarily remember the location of an icon so that it is visible if you return after
closing the archive, select the file in the dialog box and click Remember File. (To
toggle this option on and off, click the button again or press Command-R.) This
information will be lost when you quit VISE X.
After you return to the Choose Icon window, to see which icons are in the file that
is selected at the bottom of the window, press the Option key. The icons that are
part of the selected file will display a gray border.
4. Click OK. You will return to the Edit Package window, and the icon you selected
will be displayed above the Choose Icon button.
To paste an icon from a file’s Get Info window at the Finder:
1. At the Finder, copy the desired icon from the Get Info window for the application.
2. At the Edit Package window, press Command-V. The icon will be pasted into the
correct location.
To paste an icon from an item’s Get Info window within VISE X:
1. At the archive window, select the file whose icon you wish to use.
2. Click Get Info.
3. In the item’s Info window, click on the icon.
4. Press Command-C to copy the icon.
5. Return to the Edit Package window for the package you’re editing, and press
Command-V to paste the icon.
Rearranging the List
of Packages
Packages will be displayed in the Packages window in the order in which you created them.
To reorder the list of packages:
1. Hold down the mouse button on the package or on the separator. The pointer will
turn into a hand as soon as you move the cursor with the mouse button held
down.
2. With the mouse button held down, drag the package or separator to the desired
location.
3. Release the mouse. The package or separator line will remain in the location where
you dropped it.
Sub-packages, which appear indented, will be associated with the first regular package that
appears above them. In the following illustration, the sub-packages “Database Samples,”
Chapter 4 Creating Packages And Assigning Files
VISE X User’s Guide
Deleting a Package
4–23
“Spreadsheet Samples,” and “Word Processing Samples” are associated with the regular
package “Samples.”
Illustration 4-21: Package List Window
When the customer runs the installer, those sub-packages will be displayed in that order
beneath the Samples package. However, you must assign files that are part of sub-packages
to both the parent package and appropriate sub-package to be installed correctly; changes
that you make in this window only affect the appearance and behavior of the Custom
Install window, not the installer in general.
Deleting a Package
The Easy Install package can not be deleted from the list.
To delete any other package:
1. At the Packages window, select the name of the package.
2. Click Delete.
Assigning Items to
Packages
You may assign items in the archive to as many packages as you wish. Packages which have
no files assigned to them will be identified by archive reports. Files may be assigned to
packages in three ways:
■
Through a Packages popmenu in the archive window detail
■
By selecting the desired packages in the packages column of the archive window
■
Through the Packages popmenu in the item’s Get Info window
If you’ve created sub-packages, you must assign items to the appropriate sub-package and to the parent package. For example, if your
installer includes a parent package called “Samples” and sub-packages
called “Database samples” and “Spreadsheet samples,” you must
assign the desired contents of the “Database samples” and “Spread-
VISE X User’s Guide
Section 2 Building an Installer
4–24
Assigning Items to Packages
sheet Samples” packages both to the appropriate sub-package and to the Samples package.
Assigning Items in the
Packages popmenu
To assign items to packages using the Packages popmenu:
1. In the archive window, select the item you wish to assign to a package.
2. Hold down the mouse over the Packages popmenu in the archive window detail
area. A list of the packages you created will be displayed.
3. Select the package to which you wish to assign the item.
If you wish to assign the item to more than one package, highlight
the name of the desired package in the list and press the Space bar.
A check will be displayed next to the name of the package, and the
popmenu will remain displayed so you can select more packages. You
can then drag the mouse to the next package you wish to assign, and
use the same procedure to select the package.
Removing Items From
Packages
To remove an file or folder from a package, follow the steps as described above. When you
select a package that has a check next to it, the check will be removed and the file will no
longer be part of that package.
As in the preceding section, you can toggle between selecting and
deselecting a package without releasing the mouse by highlighting
the name of the package in the popmenu and pressing the Space
bar.
Creating New Packages
on the Fly
To create a new package on the fly, select New Package... from the Packages popmenu.
The Packages window will be displayed, and you may create a new package as described in
the preceding section.
Chapter 4 Creating Packages And Assigning Files
VISE X User’s Guide
Assigning Items to Packages
4–25
Assigning Items to
If you are using the Standard archive window layout (or any layout which has packages in
Packages in the Archive the column area) you can expand the archive window so that the names of the packages
to which the items are assigned is displayed right.
Window
Illustration 4-22: Archive window displaying package assignments
To see more or less of the package names, drag the double-line that separates the headings
from the items in the archive up or down.
Assigning Items to
Packages
To assign an item to a package in the archive window:
1. Place the mouse on the same line as the file or folder you wish to assign to a package.
2. Move the mouse to the column for the desired package. As a visual aid, the name
of the package will be highlighted when the mouse is in its column.
3. When the name of the desired package is highlighted, click the mouse. An X will
appear in the column for the package.
VISE X User’s Guide
Section 2 Building an Installer
4–26
Chapter 4 Creating Packages And Assigning Files
Assigning Items to Packages
VISE X User’s Guide
5–1
Chapter 5
Creating Action Items
What Are
Action Items?
VISE X User’s Guide
Action items are objects you create within an archive that perform common functions for
which you might otherwise have to write external code. Action items allow you to do the
following:
■
Find items on the customer’s system. You may use the result of the action item
to move existing files or install new files to the location where the item you
looked for was found.
■
Delete items on the customer’s system.
■
Copy items on the customer’s system to a new location.
■
Move items on the customer’s system to a new location.
■
Rename items on the customer’s system.
■
Create aliases of items in the archive and place them in a specific location on the
customer’s system.
■
Display message dialogs that can conditionally install, delete, or rename files
based on a user's response.
■
Display forms that can query the user for information and set runtime variables
based on the user’s response.
■
Set and Test runtime variables.
■
Move backward or forward in the install sequence, so the installer can execute an
install item one or more times, or bypass it entirely.
■
Conditionally stop the installation.
■
Sub-launch applications or other VISE X installers.
■
Launch the default web browser on the customer’s system and open a specified
URL.
■
Edit text files on the customer’s system. These edits can include adding, deleting
and replacing text.
Section 2 Building an Installer
5–2
Creating an Action Item
■
Add items to or remove items from the Mac OS X Dock or Startup Items.
■
Check whether or not the user has permission to install to a given location.
■
Execute UNIX shell scripts to perform various actions on the user’s system.
You may set up the action items to be performed on installations and/or on removals.
Additionally, you may set them up so that if the action item fails, the installation or
removal is canceled. (The exception to these conditions is the Comment action item,
whose sole function is to note logic in the installer archive.)
Basic Steps
The basic steps for working with action items are:
1. Create the Action item.
2. Name the Action item.
3. Set options for the Action item, such as whether the action takes place as a result
of a Gestalt check.
4. Close and Save the Action item.
5. Assign the Action item to packages.
Creating an Action
Item
To create an action item:
1. At the top right of the archive window, select an action item from the Action Item
popmenu. Or, select an action item from the Archive menu.
Illustration 5-1: Action Item popmenu
Chapter 5 Creating Action Items
VISE X User’s Guide
Creating an Action Item
5–3
2. The Action Item window will be displayed. For illustration purposes we have chosen an Alias Action item.
Illustration 5-2: Example Action Item Window
Action items are divided into four sections:
VISE X User’s Guide
■
Name and general information
■
<Action> If
■
What to <Action>
■
<Action> Options
Section 2 Building an Installer
5–4
Entering General
Information
Creating an Action Item
For each action item created you will need to enter an action item name and general information about when the action item should be performed and whether installations and
removals should be halted if the item fails.
Illustration 5-3: Action Item General Information Area
To enter action item general information:
1. Enter a name for the action item.
2. If you want the action item to be performed during an installation, select Perform
on Installs. By default, this item is selected.
3. If you want the action item to be performed during a removal, select Perform on
Uninstall. By default, this item is not selected.
4. If you want the installer’s action to stop if the selected action fails, select Stop
Install if <Action> Fails, where <Action> is the kind of action that you identified. By default, this item is not selected.
When executed, a Stop Install if <Action> Fails will stop the
installation and delete any files installed up to that point. However,
it will not undo any other changes made by the installer, such as
items deleted, copied, moved or renamed, aliases created and text
files edited.
Entering <Action> If
Information
Settings in this area let you determine the circumstances under which the action item will
be executed.
To enter <Action If> Options:
Assigning Build Directives
to Action Items
1. If you have opted to use the Advanced Project Management feature Build Directives and you want to limit the inclusion of the action item to specific installer
builds, hold down the mouse over the Build Directives popmenu.
Build Directives serve as limiting agents for action items. If no build directives are
checked, the inclusion of the action item in an installer build will not be limited.
Another way to say the same thing would be that if no items are checked in the
Build Directive popmenu, this action item will always be included when an installer
Chapter 5 Creating Action Items
VISE X User’s Guide
Creating an Action Item
5–5
is built.
Illustration 5-4: <Action> If Options
The Build Directives popmenu will display any build directive that has been set up
in the Build Directive window as well as the Any Match item.
If only one build directive item is checked, as in the example below, this action
item will be included in the built installer only when that build directive is in effect.
Checking multiple items in the Build Directive popmenu will result in an AND
condition. In the example below, this action item will be included in the installer
when the Debug Build AND the English Release build directives are in effect.
The Any Match item causes an OR condition to be in effect for any other checked
items.
In the example below, this action item will be included in the installer when Debug
Build OR English Release is in effect.
If no items are checked in the Build Directive popmenu, this action item will
always be included when an installer is built.
Any item in the Archive Window item list, including action items,
which has no build directives specified will always be included in the
built installer.
Gestalt
VISE X User’s Guide
2. If you wish the action to be performed based on a gestalt check, hold the mouse
over the Gestalt popmenu. The Gestalt popmenu lets you select the gestalt calls
Section 2 Building an Installer
5–6
Entering What to <Action> Information
that will be made to evaluate the target system. During installation, if the requirements of the gestalt call(s) are not met, the action item will not be executed.
Languages
3. If you wish the action to be performed based on a language check, hold the mouse
over the Language popmenu. During installation, if the user’s computer is not of
the language specified, the action item will not be executed.
Region
4. If you wish the action to be performed based on a region check, hold the mouse
over the Region popmenu. During installation, if the user’s computer is not of the
region specified, the action item will not be executed.
When there are check marks on items in both the Language and the
Region popmenus it represents an AND condition. Multiple check
marks within one popmenu act as an OR condition.
Action Results
If you wish the action to be performed based upon the success or failure of another
action item, click the button titles Click to Assign. Action Results allow the
action item to be executed based upon the result of another action item. When the
Click to Assign button is clicked, the Select Action Item window allows the selection of any action item already defined within the archive.
Illustration 5-5: Select Action Item for Action Result
If a Test Variable action item is selected, you can then choose between true and
false. If a Message action item is selected, you can choose between button names in
the message dialog. For all other action items, you choose between success or failure.
Entering What to
<Action>
Information
The What to <Action> section of the action item window determines what items will be
acted upon. The information in this section is relevant for all action items except Message,
Form, Set Variable, Test Variable, Jump, Stop, Launch URL, Comment and UNIX Script
action items.
Chapter 5 Creating Action Items
VISE X User’s Guide
Entering What to <Action> Information
5–7
What to <Action> has three search options.
Switching between these options switches other corresponding options and, in the case of
the Find Action Item and the Archive Item, resizes the action item window itself.
Items Found Using
Search Criteria
When Items Found Using Search Criteria is selected in the What to <Action> popmenu, the Search Location and Search Criteria areas are expanded so that the search for
the action can be completely defined.
Illustration 5-6: What to <Action> with Items Found Using Search
Criteria
Find Action Item
When Find Action Item is selected in the What to <Action> popmenu, the Search Location and Search Criteria areas are collapsed because the search will be defined by the Find
action selected. When Find Action Item is selected in the What to <Action> popmenu,
the Find Action Item popmenu will contain a list of all Find actions currently defined
within the archive. When set up in this manner, one Find action can be used to set the
search criteria for a number of other actions minimizing the need to perform the same
search multiple times.
Illustration 5-7: What to <Action> using Find Action Item
VISE X User’s Guide
Section 2 Building an Installer
5–8
Archive Item
Entering What to <Action> Information
When Archive Item is selected in the What to <Action> popmenu, the Search Location
and Search Criteria areas are collapsed because the action will be performed on the
archive item specified after that item is installed.
Illustration 5-8: What to <Action> using Archive Item
When using the What to <Action> with an Archive Item, make sure
the action item is after the Archive Item in the Archive window. An
action set up in this way will perform correctly only if the installation of the Archive Item precedes the action item execution.
To use Items Found Using Search Criteria:
1. If you wish to change the beginning search location and other identifying information to search for a file of folder, select Items Found Using Search Criteria.
2. By selecting domains in conjunction with search locations, you can find files and
folders that are specific to a given domain. Make your selection from the Domain
popmenu. Your options are:
Chapter 5 Creating Action Items
■
System Domain
■
Local Domain
■
Network Domain
■
User Domain
■
Classic Domain (This domain enables installers launched on Mac OS X to
install files to the Classic environment.)
VISE X User’s Guide
Entering What to <Action> Information
5–9
3. Select search location from the Search Location popmenu.
Illustration 5-9: User Domain Search Locations
The Search Location popmenu for User Domain is shown above. (User Domain is
the default Domain setting for action items that include Search Location and
VISE X User’s Guide
Section 2 Building an Installer
5–10
Entering What to <Action> Information
Install To popmenus.) A number of additional items may also appear in this popmenu, depending on your setup. For complete instructions on how to add or
remove these extended locations, see Chapter 29-Install Locations.
From the Search Location popmenu, select one of the following items:
Popmenu Item
Search Location
Installer Volume
Searches the volume where the installer is located.
Startup Disk
Searches the boot volume of the customer’s system
Selected Disk
Searches the destination volume selected by the customer
for the installation. (If you want to limit the customer to
installing only on local disks, you must make sure that
Allow Installation to Mounted Servers is deselected at
the Installer Settings/Behavior tab. Also, to prevent the
customer from installing on UNIX File System disks, make
sure that Allow Installation to UFS Volumes is
deselected at the Installer Settings/Behavior tab.)
All Disks
Searches all mounted drives if the Allow Installation to
Mounted Servers option is selected at the Installer
Settings/Behavior tab. (UNIX File System disks can be
included in the search only if the Allow Installation to
UFS Volumes option is selected at the Installer Settings/
Behavior tab.) If Allow Installation to Mounted Servers
is not selected, then only local volumes will be searched
Current Folder
The current folder is the enclosing folder of the action
item in the archive.
Install Folder
The install folder is the location in the folder hierarchy
selected by the customer for the installation.
Ask User
Searches the location indicated by the users selection in a
dialog.
Find Action Result…
Searches the location indicated by the designated Find
Action item.
Root of Startup Disk
Searches the root level of the startup volume
Table 5-1: Action Item Search Locations
The remaining items search the folders of that name.
Some locations do not exist under older Mac OS versions. If you
plan to use a location that is not supported on an OS version your
customers may be using, you should create a gestalt check to ensure
that these locations exist, or deselect the Stop Install if “<type of
action>“ Fails item at the top of the Action Item window.
If the item you’re searching for is a file, make sure File is selected to the right of the
Search Location popmenu. If the item you’re searching for is a folder, select Folder to the
Chapter 5 Creating Action Items
VISE X User’s Guide
Entering What to <Action> Information
5–11
right of the Search Location popmenu. If the item you’re searching for is a Mac OS X
bundle, select Bundle to the right of the Search Location popmenu.
Configuring Search
Options
After selecting an item to be searched for there are a number of other options which you
may want to set. From the checkboxes below the file/folder radio buttons select from the
following options:
Option
Description
Match Can be Alias
If checked, the search will find aliases which match the
search criteria. If the Match Can be Alias is not checked,
only files or folders will be found.
Search Locked Volumes
Allows locked volumes such as CDs to be included in the
search.
Search Subfolders
If checked, searches for items matching the search criteria
will continue through subfolders. If Search Subfolders is not
checked, searching will not take place in subfolders.
Find Multiple
Occurrences
If checked, Find Multiple Occurrences allows the search to
return multiple matches to the search criteria. If Find
Multiple Occurrences is not checked, the first item
matching the search criteria will be used. When Find
Multiple Occurrences is checked, other options in the
<Action> Options area are available which can allow you to
present a list of found items to the user for their choice or
to present an action confirmation dialog to the user. For a
complete discussion of the Confirm options and the User
Prompt option, see “Confirm Delete” on page 5-20,
“Confirm Copy” on page 5-21, “Confirm Move” on
page 5-22, “Confirm Rename” on page 5-24, , “Confirm
Creating Alias” on page 5-25, “Confirm Edit File” on
page 5-40 and “Confirm Action” on page 5-44.
Table 5-2: What to <Action> Search Options
Identifying Search Criteria If you are searching for a folder, you may only identify the name of the folder. If you are
searching for a bundle, you may identify the name and version number of the bundle. If
you are searching for a file, you may work with any or all of the following criteria:
Item name
Description
Name
The name of the item.
Type
The four-character type identifier of the file.
Creator
The four-character creator identifier of the file.
Version
The version number of the file. You may specify the version
number up to two decimal places. You may also identify whether
the file is a development, alpha, beta, or final version, based on
the contents of the file’s vers resource. (If desired, you may
search for a range of version numbers.)
Table 5-3: Action Item Search Criteria
VISE X User’s Guide
Section 2 Building an Installer
5–12
Entering What to <Action> Information
Item name
Description
Date Created
The creation date of the file. (If desired, you may search for a
range of creation dates.)
Date Modified
The modification date of the file. (If desired, you may search for
a range of modification dates.)
Table 5-3: Action Item Search Criteria
The action item will search for items that meet all of the criteria that you identify in the
Search Criteria section.
Because a customer may have changed the name of an item at the
Finder, consider using additional criteria such as type, creator, and
version number rather than name to identify specific items on the
target system.
Drag and Drop Shortcuts
in Action Item windows
The following drag and drop shortcuts are available:
■
Dragging an item from the Finder onto an Action Item window (except Message,
Form, Set Variable, Test Variable, Jump, Stop, Launch URL, Comment and
UNIX Script actions) will assign that item’s attributes.
■
Dragging an item from the archive window onto an Action Item window (except
Message, Form, Set Variable, Test Variable, Jump, Stop, Launch URL, Comment
and UNIX Script actions) will assign the attributes of the item.
Dragging a bundle onto an Action Item window (using either of the
two shortcuts above) will set the action to search for the name of the
executable inside the bundle (in case the end user has changed the
bundle name). An installer executing the action will search by the
executable name and display found items by the current bundle
name.
Identifying the Name (Files To specify information about the name of the item you wish to search
for:
Folders and Bundles)
1. Make sure that the Name checkbox is checked.
Chapter 5 Creating Action Items
VISE X User’s Guide
Entering What to <Action> Information
5–13
2. Hold down the mouse over the popmenu to the right of the Name item and select
one of the following items:
Name
Search Criteria
Searches for items that contain the character string
entered in the Name field anywhere in their name.
Searches for items whose names begin with the
character string entered in the Name field.
Searches for items whose names end with the character
string entered in the Name field.
Searches for items with the exact character string
entered in the Name field. (This is the default setting.)
Searches for items whose names are not the exact
character string entered in the Name field.
Table 5-4: Action Item Search Criteria-Name
3. In the Name field, enter the character string of the name. (For bundle searches, this
should be the name of the executable inside the bundle).
Specifying File Type
Information (Files Only)
To specify search information about the file type:
1. Select the Type item.
2. Hold down the mouse over the popmenu to the right of Type and select one of the
following:
Type
Search Criteria
Searches for files whose type matches the file type
entered in the Type field. (This is the default setting.)
Searches for files whose type does not match the file
type entered in the Type field.
Table 5-5: Action Item Search Criteria-File Type
3. In the Type field, enter the four-character file type you wish to search for.
Specifying File Creator
Information (Files Only)
VISE X User’s Guide
To specify information about the creator of the file:
1. Select the Creator item.
Section 2 Building an Installer
5–14
Entering What to <Action> Information
2. Hold down the mouse over the popmenu to the right of Creator and select one of
the following:
Creator
Search Criteria
Searches for files whose create matches the creator
type entered in the Creator field. (This is the default
setting.)
Searches for files whose creator does not match the
creator type entered in the Creator field.
Table 5-6: Action Item Search Criteria-File Creator
3. In the Creator field, enter the file’s four-character creator identifier.
Specifying Version
Information (Files and
Bundles Only)
To specify the version number of the file or bundle:
1. Select Version.
2. Hold down the mouse over the popmenu to the right of the Version item and
select one of the following:
Version
Search Criteria
Searches for items whose version numbers exactly
match the numbers that you enter in the version
number fields. (This is the default setting.)
Searches for items whose version numbers are less than
the numbers that you enter in the version number
fields.
Searches for items whose version numbers are less than
or equal to the numbers that you enter in the version
number fields.
Searches for items whose version numbers are greater
than the numbers that you enter in the version
number fields. (This option lets you search for a range
of version numbers.)
Searches for items whose version numbers are greater
than the numbers that you enter in the version
number fields. (This option lets you search for a range
of version numbers.)
Searches for any items whose version numbers are not
the numbers that you enter in the version number
fields.
Table 5-7: Action Item Search Criteria-Version
Chapter 5 Creating Action Items
VISE X User’s Guide
Entering What to <Action> Information
5–15
3. In the version number fields, enter the item’s version number. For example, to
search for an item with version number 3.1.5, the fields would look like this:
4. If you wish to specify additional information based on the vers resource of the target item:
■
Hold down the mouse over the popmenu to the right of the version number entered in the previous step.
■
As desired, select Final, Development, Alpha, or Beta.
■
In the field to the right of the vers resource identifier, enter the version
number.
For example, to search for a file with version number 3.1.5 that’s designated as beta
6, the fields would look like this:
In version comparisons, the highest possible value for a vers resource
number is zero. For example, version number 3.1.5 beta 6 would be
less than 3.1.5 beta 0.
5. If you selected Is greater than or Is > or equal, you may specify the range of
version numbers to search. The item that you entered in Step 4 identifies the low
end of the search range; in this step, you’ll identify the high end of the range.
To specify the high end of the range:
■
Click AND. (This item becomes active if you selected Is greater than or Is
> or equal for the Version item in the Search Criteria panel.)
■
To set the range to include version numbers that are less than the numbers
you will enter in the version number fields, select Is less than; to search for
items whose version numbers are less than or equal to the number you enter
in the version number fields, select Is < or equal.
■
In the version number fields, enter the version numbers that signify the high
end of the range to search for. Use the same format to enter the version
numbers as you did in Step #4.
For example, to search for an item with version number between 3.1.5 beta 6 but
less than version 4.2, the fields would look like this:
VISE X User’s Guide
Section 2 Building an Installer
5–16
Entering What to <Action> Information
When searching for bundle version, installers use the bundle version
inside the .plist file in addition to the older-style 'vers' resource.
How VISE X Checks For
Bundle Version
To automatically recognize folder structures as bundles when they are added to the
archive, VISE X checks that the items meet at least one of the following criteria:
■
■
The folder has one of the following filename extensions:
■
.app
■
.bundle
■
.framework
The folder has a bundle bit set (kHasBundleBit).
To have VISE X recognize your item as a bundle for this drag and drop scenario, you can
do one of the following:
■
Change the filename extension to one of the three previously listed.
■
Use a resource editor such as Resorceror to turn on the folder flag
kHasBundleBit for the bundle.
■
Add your bundle’s filename extension to the text file “Bundle Extensions.txt” in
the VISE X Extensions folder. VISE X will then treat folder structures with your
specified extension as bundles. The VISE X Extensions folder is located within
the builder’s application bundle at: VISE X.app/Contents/Resources/VISE X
Extensions.
Though you can add a folder structure to the archive and then set its
kHasBundleBit with the Application Bundle checkbox, this
approach will not allow VISE X to read version information for the
structure. To enable proper version checking for actions such as Find
and Replace, you should set up your folder structure as described
here (if needed) before adding it to your archive.
When you add a recognized bundle to the archive or drag it into the Search Criteria area
of an action item window or the Default Install Location window, VISE X checks for bundle version as follows:
1. The program makes an Apple API call to CFBundleGetVersionNumber. That API
call returns the value of the CFBundleVersion string from the Info.plist file inside
the bundle. (To be valid, the string data needs to be in “##.#.#” format as defined
in Apple Technical Note TN1132.)
2. If CFBundleGetVersionNumber returns a zero, VISE X will try calling CFBundleGetValueForInfoDictionaryKey, passing CFBundleShortVersionString to obtain
the bundle's version. We have noticed CFBundleGetVersionNumber returns a zero
when the CFBundleVersion field is three or more digits (as is the case with AddressBook.app and Mail.app).
3. If both of these checks return zero, VISE X sets the bundle version to zero.
Chapter 5 Creating Action Items
VISE X User’s Guide
Entering What to <Action> Information
Specifying Creation Date
Information (Files Only)
5–17
To specify information about the creation date of the file:
1. Select Date Created.
2. Hold down the mouse over the popmenu to the right of the Date Created item
and select one of the following:
Creation Date
File Type Search Criteria
Searches for files whose creation dates exactly match
the date that you enter in the date created fields. (This
is the default setting.)
Searches for files whose creation dates are less than the
date that you enter in the creation date field.
Searches for files whose creation dates are less than or
equal to the date that you enter in the creation date
fields.
Searches for files whose creation dates are greater than
the date that you enter in the creation date fields.
(This option lets you search for a range of creation
dates.)
Searches for files whose creation dates are greater than
the date that you enter in the creation date fields.
(This option lets you search for a range of creation
dates.)
Searches for any files whose creation date are not the
dates that you enter in the creation date fields.
Table 5-8: Action Item Search Criteria-Creation Date
3. In the fields to the right of the popmenu, enter the creation date you wish to
search for, in the month/day/year format. (Today’s date will appear in the field by
default.) For example, to specify a creation date of October 16, 2003, the fields
would look like this:
4. If you selected Is greater than or Is > or equal, you may specify the range of
dates to search. The item that you entered in Step 3 identifies the low end of the
search range; in this step, you’ll identify the high end of the range.
To specify the high end of the range:
VISE X User’s Guide
■
Click AND. (This item becomes active if you selected Is greater than or Is
> or equal for the Date Created item in the Search Criteria panel.)
■
To set the range to include creation dates that are less than the numbers you
will enter in the creation date fields, select Is less than; to search for files
whose creation dates are less than or equal to the number you will enter in
the creation date fields, select Is < or equal.
Section 2 Building an Installer
5–18
Action Options
■
In the creation date fields, enter the creation dates that signify the high end
of the range to search for. Use the same format as you did in Step #3.
Specifying Modification
Date Information (Files
Only)
To specify information about a modification date, select Date Modified and follow the
steps for “Specifying Creation Date Information,” described above, entering modification
date information the appropriate fields. You may use the same procedure to specify a
range of dates, using the Modification Date fields in the Search Criteria panel.
Action Options
The options area of the Action Item window contains items specific to the type of action.
Below are illustrations of the options area for each Action item.
Find Options
Illustration 5-10: Find Action Item - Find Options
Option
Description
Return <x> Level(s)
Above Found Item
When checked on, the Find action will return the path
to a folder in the hierarchy above the found item, rather
than the path to the item itself. The included text field
accepts digits from 1-99 and determines the number of
levels above the found item that VISE X should go to
perform the Find action.
Open/Launch Found
Items
When checked on, the Find action will open or launch
the found items.
User Prompt
Text entered here will be used in the confirmation
dialog presented to the user when running the installer.
See also “Use Yes/No for Action Item Confirmations”
under “Designing the Installer’s Behavior” on
page 10-18.
Table 5-9: Find Options (Sheet 1 of 2)
Chapter 5 Creating Action Items
VISE X User’s Guide
Action Options
5–19
Option
Description
Set Variable
A runtime variable assigned here will be used to store
the full path to the found items. The variable can then
be tested with Test Variable actions, and used in various
ways to control install logic. For more information on
variables, see Chapter 22-Using Runtime Variables.
Save as POSIX Path
By default, a Find action set to store its results in a
runtime variable will return a colon-separated full path
to the found item. This is the correct type of path for
access to files and folders on Mac OS X. However, if
you use variable substitution to pass a path in a UNIX
Script action, the variable must be set with a POSIXbased (slash-separated) path to conform to UNIX
standards. This is the purpose of the Find action’s Save
as POSIX Path setting. (Also see “UNIX Script Options”
on page 5-48.)
Table 5-9: Find Options (Sheet 2 of 2)
Delete Options
Illustration 5-11: Delete Action Item - Delete Options
Option
Description
Delete <x> Level(s)
Above Found Item
When checked on, the Delete action will delete a folder
in the hierarchy above the found item. (Consequently,
the action will delete everything contained in the folder
hierarchy, including the found item.) The included text
field accepts digits from 1-99 and determines the
number of levels above the found item that VISE X
should go to perform the Delete action.
Delete Folder Only If
Empty
When checked on, a found folder will only be deleted if
it is empty.
Table 5-10: Delete Options (Sheet 1 of 2)
VISE X User’s Guide
Section 2 Building an Installer
5–20
Action Options
Option
Description
Confirm Delete
Before the Delete action takes place on the item(s)
found using the settings in What to Delete, the user is
asked to confirm the action. If Find Multiple
Occurrences is also checked, the confirmation is
effective for all items found. The text for the
confirmation message can be entered in the User
Prompt text field.
Display Found Items
Display Found Items can only be checked on if
Confirm Delete is also checked on. When both are on,
during an install the user will be presented with a list
containing item(s) found using the settings in What to
Delete. The items selected by the user in the list will
then be deleted. The text for the confirmation message
can be entered in the User Prompt text field.
User Prompt
Text entered here will be used in the confirmation
dialog presented to the user when running the installer.
See also “Use Yes/No for Action Item Confirmations”
under “Designing the Installer’s Behavior” on
page 10-18.
Table 5-10: Delete Options (Sheet 2 of 2)
Copy Options
Illustration 5-12: Copy Action Item - Copy Options
Chapter 5 Creating Action Items
VISE X User’s Guide
Action Options
5–21
Option
Description
Copy <x> Level(s) Above
Found Item
When checked on, the Copy action will copy a folder in
the hierarchy above the found item. (Consequently, the
action will copy everything in the hierarchy from the
folder to the found item, inclusive.) The included text
field accepts digits from 1-99 and determines the
number of levels above the found item that VISE X
should go to perform the Copy action.
Confirm Copy
Before the Copy action takes place on the item(s) found
using the settings in What to Rename, the user is asked
to confirm the action. If Find Multiple Occurrences is
also checked, the confirmation is effective for all items
found. The text for the confirmation message can be
entered in the User Prompt text field.
Display Found Items
Display Found Items can only be checked on if
Confirm Copy is also checked on. When both are on,
during an install the user will be presented with a list
containing item(s) found using the settings in What to
Copy. The items selected by the user in the list will then
be renamed. The text for the confirmation message can
be entered in the User Prompt text field.
User Prompt
Text entered here will be used in the confirmation
dialog presented to the user when running the installer.
See also “Use Yes/No for Action Item Confirmations”
under “Designing the Installer’s Behavior” on
page 10-18.
Copy To Location
Designates the location to which the found item will be
copied.
Domain
Designates the domain to which the found item will be
copied. For more information on setting a domain for
archive items, see “Domain Location” on page 9-9.
New Name
This text field is used to determine the new name of the
item being acted upon.
Replace
Replace options determine the action to be taken when
renaming would result in a name collision. For a
complete discussion of action item replace options see
“Replace Options” on page 5-50.
Table 5-11: Copy Options
VISE X User’s Guide
Section 2 Building an Installer
5–22
Action Options
Move Options
Illustration 5-13: Move Action Item - Move Options
Option
Description
Move <x> Level(s) Above
Found Item
When checked on, the Move action will move a folder
in the hierarchy above the found item. (Consequently,
the action will move everything in the hierarchy from
the folder to the found item, inclusive.) The included
text field accepts digits from 1-99 and determines the
number of levels above the found item that VISE X
should go to perform the Move action.
Confirm Move
Before the Move action takes place on the item(s) found
using the settings in What to Move, the user is asked to
confirm the action. If Find Multiple Occurrences is also
checked, the confirmation is effective for all items
found. The text for the confirmation message can be
entered in the User Prompt text field.
Display Found Items
Display Found Items can only be checked on if
Confirm Move is also checked on. When both are on,
during an install the user will be presented with a list
containing item(s) found using the settings in What to
Delete. The items selected by the user in the list will
then be deleted. The text for the confirmation message
can be entered in the User Prompt text field.
User Prompt
Text entered here will be used in the confirmation
dialog presented to the user when running the installer.
See also “Use Yes/No for Action Item Confirmations”
under “Designing the Installer’s Behavior” on
page 10-18.
Move To Location
Designates the location to which the found item will be
moved.
Table 5-12: Move Options (Sheet 1 of 2)
Chapter 5 Creating Action Items
VISE X User’s Guide
Action Options
5–23
Option
Description
Domain
Designates the domain to which the found item will be
moved. For more information on setting a domain for
archive items, see “Domain Location” on page 9-9.
Replace
Replace options determine the action to be taken when
moving would result in a name collision. For a complete
discussion of action item replace options see “Replace
Options” on page 5-50.
Table 5-12: Move Options (Sheet 2 of 2)
When moving items across volumes the original is left in its original
location. It functions the same as dragging the item in the Finder. If
the item is being moved from one location on a volume to another
location on the same volume, the item is copied to the new location
and the item at the original location is removed. If the item is being
moved from one location on a volume to a location on a different
volume, the item is copied to the new location and the item at the
original location remains.
Both Move and Copy action items will copy files to a drive without
checking for available space. If a disk fills up during a Move or a
Copy action, the installer will incorrectly display a message that
nothing needed to be installed.
Rename Options
Illustration 5-14: Rename Action Item - Rename Options
VISE X User’s Guide
Section 2 Building an Installer
5–24
Action Options
Option
Description
Rename <x> Level(s)
Above Found Item
When checked on, the Rename action will rename a
folder in the hierarchy above the found item. The
included text field accepts digits from 1-99 and
determines the number of levels above the found item
that VISE X should go to perform the Rename action.
Confirm Rename
Before the Rename action takes place on the item(s)
found using the settings in What to Rename, the user is
asked to confirm the action. If Find Multiple
Occurrences is also checked, the confirmation is
effective for all items found. The text for the
confirmation message can be entered in the User
Prompt text field.
Display Found Items
Display Found Items can only be checked on if
Confirm Rename is also checked on. When both are
on, during an install the user will be presented with a
list containing item(s) found using the settings in What
to Rename. The items selected by the user in the list will
then be renamed. The text for the confirmation message
can be entered in the User Prompt text field.
User Prompt
Text entered here will be used in the confirmation
dialog presented to the user when running the installer.
See also “Use Yes/No for Action Item Confirmations”
under “Designing the Installer’s Behavior” on
page 10-18.
New Name
This text field is used to determine the new name of the
item being acted upon.
Replace
Replace options determine the action to be taken when
renaming would result in a name collision. For a
complete discussion of action item replace options see
“Replace Options” on page 5-50.
Table 5-13: Rename Options
Chapter 5 Creating Action Items
VISE X User’s Guide
Action Options
5–25
Alias Options
Illustration 5-15: Alias Action Item - Alias Options
Option
Description
Alias <x> Level(s) Above
Found Item
When checked on, the Alias action will alias a folder in
the hierarchy above the found item. The included text
field accepts digits from 1-99 and determines the
number of levels above the found item that VISE X
should go to perform the Alias action.
Confirm Creating Alias
Before the Alias action takes place on the item(s) found
using the settings in What to Rename, the user is asked
to confirm the action. If Find Multiple Occurrences is
also checked, the confirmation is effective for all items
found. The text for the confirmation message can be
entered in the User Prompt text field.
Display Found Items
Display Found Items can only be checked on if
Confirm Creating Alias is also checked on. When both
are on, during an install the user will be presented with
a list containing item(s) found using the settings in
What to Alias. The items selected by the user in the list
will then be aliased. The text for the confirmation
message can be entered in the User Prompt text field.
User Prompt
Text entered here will be used in the confirmation
dialog presented to the user when running the installer.
See also “Use Yes/No for Action Item Confirmations”
under “Designing the Installer’s Behavior” on
page 10-18.
Alias Location
Designates the location to which the found item will be
aliased.
Table 5-14: Alias Options (Sheet 1 of 2)
VISE X User’s Guide
Section 2 Building an Installer
5–26
Action Options
Option
Description
Domain
Designates the domain to which the found item will be
aliased. For more information on setting a domain for
archive items, see “Domain Location” on page 9-9.
New Name
This text field is used to determine the new name of the
alias being created.
Special Notes for New Name:
If the New Name field is left blank in an Alias action,
the name for the created alias will be the name of the
item designated in the What to Alias area, suffixed with
the word “alias.”
For the Alias action, you can also use a “^0” in the New
Name field to represent the found filename. For
example, if you put “Bob’s ^0” in the name field and
the found file was named MyApp, the alias name would
be “Bob’s MyApp.”
Replace
Replace options determine the action to be taken when
aliasing would result in a name collision. For a complete
discussion of action item replace options see “Replace
Options” on page 5-50.
Table 5-14: Alias Options (Sheet 2 of 2)
Message Options
Illustration 5-16: Message Action Item - Message Options
Option
Description
Icon ID
The icon ID will determine the icon displayed in the
Message dialog. See Table 5-16, “Icon Options for
Message Action dialogs,” on page 5-27.
Message text
The text which will be displayed in the Message dialog.
Table 5-15: Message Options (Sheet 1 of 2)
Chapter 5 Creating Action Items
VISE X User’s Guide
Action Options
5–27
Option
Description
Button 2
Name for button 2
Button 1
Name for button 1
Table 5-15: Message Options (Sheet 2 of 2)
The Message Action allows you to display a message dialog to the user. You can display 1
or 2 buttons in the dialog. You can then conditionally install, delete, or rename a file
depending upon which button the user selects. You can also display a one button alert
message.
In the Icon ID field different icons can be selected for use in the message dialog.
Icon ID
Icon Displayed
0
1
2
Table 5-16: Icon Options for Message Action dialogs
For additional icon options in Message action dialogs, add cicn
resources to the archive through an external resource file. If there are
cicns in an external resource file connected to the archive, the id for
other cicns may be used. All cicns used by Message actions will be
included in the installer at build.
This message action can also be displayed depending upon the result of a Find Action. An
example would be to find an old version of an application, and ask the user if they want
to install a newer version. Depending upon the users choice, install or not install the
newer version.
To optionally display the message depending on the result of another
action item,
1. Click on the Execute If box, select a Find Action, and then select whether to show
the message if the Find Action succeeds. To display the message always, simply do
not select an Action Item.
2. Type in an Icon ID. You may use one of the default icons (0 = Stop, 1 = Note, 2 =
Caution) or type in the ID of one of your own icons. When you tab out of the ID
field, the icon should appear. You can also paste an icon into this window.
VISE X User’s Guide
Section 2 Building an Installer
5–28
Action Options
3. Type in the text of the message you wish to display.
4. Type in the names of Buttons 1 and 2. If you only wish to display one button, leave
the other button text blank.
5. Click on Stop If User Selects Button 2 if you wish the install to stop if the user
selects Button 2.
To assign a file to the result of a message action, do a Get Info on the file you want to
conditionally install, and then click on the “Install If” box and choose the Message action
you want. Also choose the button from the popmenu to the right of the “Install If” box.
In the illustration below, a Message action is being set up.
Illustration 5-17: Message Action window
When the action item above is executed in the installer, the message dialog below will be
displayed to the user.
Illustration 5-18: Message dialog as displayed in the installer
Chapter 5 Creating Action Items
VISE X User’s Guide
Action Options
5–29
Display Form Options
Illustration 5-19: Form Action Item - Display Form Options
Option
Form Name
Description
Select the name of the Form to be displayed by this
action item.
Table 5-17: Display Form Options
Form actions without a form assignment will stop a build and display an error stating that a form has not been assigned.
Set Variable Options
Illustration 5-20: Set Variable Action Item - Set Variable Options
Option
Variable to assign
Description
Click the button which reads (Click to assign) for a list
of variables.
Table 5-18: Set Variable Options
VISE X User’s Guide
Section 2 Building an Installer
5–30
Action Options
The Set Variable Action item allows variables to be set based on criteria which are available
at installer runtime. Runtime variables can be conditionally set by selecting items in the
Set Variable If section of the Set Variable Action window. Set Variable Action items can be
set to be included in an installer according to build directive and can be set to execute
conditionally based on Gestalt, Language, Region and/or the result of another action item.
In the example below, the following conditions affect the Set Variable Action’s execution:
1. This action item will only be included in a built installer when the Debug Build
build directive is on.
2. During an install, this action item will only be executed if:
■
The gestalt check on the users machine indicates that a G4 or newer processor is
present; AND
■
The language check on the users machine indicates that the French language is
being used; AND
■
The region check on the users machine indicates that the French or the French
Canadian region is being used; AND
■
The user clicked on Yes in the dialog presented by the Message Action asking if
MyApp should be installed.
Illustration 5-21: Set Variable Action item
When the action item above is executed, the runtime variable MyVar will be set to “MoveOld.” A Test Variable Action item can then be used to test the value of the MyVar variable
with other actions based upon the test.
Chapter 5 Creating Action Items
VISE X User’s Guide
Action Options
5–31
Test Variable Options
Illustration 5-22: Test Variable Action Item - Test Variable Options
Option
Description
Variable to assign
Click the button which reads (Click to assign) for a list
of variables. Selecting a variable from the list determines
the variable that will be tested by this action item.
Perform Numeric
Comparison
When checked, the variable value and the comparison
value are converted to numeric values before
comparison (10 is greater than 1). When unchecked, the
variable value and the comparison value are compared
as strings (“10” is not greater than “1”). This option
applies only to Test Variable action items.
Table 5-19: Test Variable Options
The Test Variable Action item allows the value of runtime variables to be tested. Runtime
variables can be conditionally tested by selecting items in the Set Variable If section of the
Test Variable Action window. Test Variable Action items can be set to be included in an
installer according to build directive and can be set to execute conditionally based on
Gestalt, Language, Region and/or the result of another action item.
VISE X User’s Guide
Section 2 Building an Installer
5–32
Action Options
In the example below, the runtime variable MyVar is being tested for a value equal to
“MoveOld.” Other action items could then be set to execute based upon the success or
failure of this Test Action.
Illustration 5-23: Test Variable Action item
Jump Options
Illustration 5-24: Jump Action Item - Jump Options
Chapter 5 Creating Action Items
VISE X User’s Guide
Action Options
5–33
Option
Description
Jump If
By selecting items in the Jump If section of the Jump
Action item, the jump can be set to execute
conditionally.
Jump To
Clicking the (Click to assign) button allows any item
(action item, file or folder) in the archive to be chosen
as the destination of the jump.
Table 5-20: Jump Action Options
Complex installer logic is much easier to construct and maintain with the use of Jump
actions. Jump actions enable an installer to move forward or back in the install sequence
without executing items in between. Jump actions can be executed conditionally by selecting items in the Jump If section of the Jump Action window. Jump Action items can be
set to be included in an installer according to build directive and can be set to execute
conditionally based on Gestalt, Language, Region and/or the result of another action item.
In the following illustration, the jump action has been set to execute only if a previous
Find action fails.
Illustration 5-25: Jump Action Item
The use of Jump Actions can cause an installer to have an inaccurate
“Number of Files to install” display in the installer progress.
VISE X User’s Guide
Section 2 Building an Installer
5–34
Action Options
Stop Installation
Options
Illustration 5-26: Stop Action Item - Stop Options
Option
Stop Install If
Description
By selecting items in the Stop Install If section of the
Stop Install Action item, the stop can be set to execute
conditionally.
Table 5-21: Stop Action Options
Stop Installation actions enable an installer to be programmatically stopped. Stop actions
can be executed conditionally by selecting items in the Stop Install If section of the Stop
Action window. Stop Installation Action items can be set to be included in an installer
according to build directive and can be set to execute conditionally based on Gestalt, Language, Region and/or the result of another action item.
In the following illustration, the Stop action has been set to execute only if a previous
Find action succeeds.
Illustration 5-27: Stop Action Item
If you turn on the Stop Install With Error checkbox, the installer will delete any files it
had installed before the Stop action was performed. If you turn on the Also Quit
Installer checkbox, the installer will quit after the Stop action executes, so the user
doesn’t have to manually quit the installer. You may want to include a Message Action
before this Stop action, telling the user why the installation failed.
Chapter 5 Creating Action Items
VISE X User’s Guide
Action Options
5–35
Sub-launch Action
Options
Illustration 5-28: Sub-launch Action Item - Sub-launch Options
Option
Description
Sub-launched item is a
VISE X Installer
If the sub-launched item is a VISE X installer, the VISE
Options become available.
NOTE: VISE Options will only work with installers
created with VISE X.
VISE Options in the parent installer will not override
Sub-launch locks set in the sub-launched installer
Behavior tab of Installer Settings. For more information
on Sub-launch locks see “Sub Launch Locks” on
page 10-21.
Wait for sub-launched
item to complete
If checked, the parent installer will wait for the sublaunched item to complete before progressing.
Show Splash Screen
If unchecked, the Splash Screen of the sub-launched
installer will not be displayed.
NOTE: VISE Options in the parent installer will not
override Sub-launch locks set in the sub-launched
installer Behavior tab of Installer Settings. See “Sub
Launch Locks” on page 10-21.
Show Read Me
If unchecked, the Read Me of the sub-launched installer
will not be displayed.
NOTE: VISE Options in the parent installer will not
override Sub-launch locks set in the sub-launched
installer Behavior tab of Installer Settings. See “Sub
Launch Locks” on page 10-21.
Table 5-22: Sub-launch Action Options (Sheet 1 of 2)
VISE X User’s Guide
Section 2 Building an Installer
5–36
Action Options
Option
Description
Show License Agreement
If unchecked, the License Agreement of the sublaunched installer will not be displayed.
NOTE: VISE Options in the parent installer will not
override Sub-launch locks set in the sub-launched
installer Behavior tab of Installer Settings. See “Sub
Launch Locks” on page 10-21.
Show Billboards
If unchecked, the Billboards of the sub-launched
installer will not be displayed.
NOTE: VISE Options in the parent installer will not
override Sub-launch locks set in the sub-launched
installer Behavior tab of Installer Settings. See “Sub
Launch Locks” on page 10-21.
Suppress
Select from the Suppress popmenu to suppress the sublaunched installer’s Main Window, the Progress Stop
and/or Success.
Packages
Select from the Packages popmenu to pre-select sublaunched installer packages for installation.
NOTE: VISE X counts Separators in the Packages List as
individual packages. For instance, “Package 2” in the
Packages popmenu could refer to a Separator. For more
information on Separators, see “Creating Package
Separators and Mutual Exclusive Groups” on page 4-10.
Send Install Location
If checked, the parent installer will send the sublaunched installer the location the user chose for the
main install. The sub-launched installer will then use
that install location as the default. NOTE: When using
this option with a sub-launched installer that requires
Mac OS X authentication, the parent installer also must
require authentication. Otherwise, when the sublaunched installer authenticates it will lose the install
location sent by the parent. With both the parent and
the sub-launch installer set to require authentication,
the user will only be prompted to authenticate once.
For information on setting installers to require Mac OS
X authentication, see “Assigning Minimum
Requirements for Installation” on page 10-23
Hide Progress Bar
If checked, the sub-launched installer will use the
progress bar of the parent installer, rather than display
its own progress bar.
Table 5-22: Sub-launch Action Options (Sheet 2 of 2)
Complete control over sub-launched applications (including other installers) is possible
through the Sub-launch Action. Since the Sub-launch item is a VISE X action item, it has
Chapter 5 Creating Action Items
VISE X User’s Guide
Action Options
5–37
all of the power of conditional execution and searching of the other action items with
added options specifically tailored to launching and controlling other installers.
Illustration 5-29: Sub-launch Action Item
In the preceding illustration, our parent installer is set to sub-launch a QuickTime installer
if a gestalt test for the existence of QT6 on the user’s machine indicates that QT6 is not
present. The parent installer will search the installer volume (in our case a CD and therefore a locked volume) for a specific application. The parent installer is set to wait for the
sub-launched installer to finish before progressing. Since the sub-launched installer is a
VISE X installer the sub-launched QT6 installer will be sub-launched displaying Splash
VISE X User’s Guide
Section 2 Building an Installer
5–38
Action Options
Screen, License Agreement, Read Me and Billboards while suppressing the Main Window,
the Progress Stop and the Success. Packages 1, 2, and 3 will be automatically chosen for
the user.
You can use external code to send information from the parent
installer to the sub-launched installer. See “Sending Information to
Sub-launched Installers” on page 26-19.
Launch URL Options
Illustration 5-30: Launch URL Action - Launch URL Options
Option
Launch URL Path
Description
This text area should contain a single URL, such as
http://acompany.com or www.mindvision.com.
Table 5-23: Launch URL Action Options
You can use the Launch URL action item to launch the default web browser on the customer’s system and open a specified URL. Launch URL actions can be executed conditionally by selecting items in the Launch URL If section of the Launch URL Action
window. Launch URL action items can be set to be included in an installer according to
build directive and can be set to execute conditionally based on Gestalt, Language, Region
and/or the result of another action item.
Chapter 5 Creating Action Items
VISE X User’s Guide
Action Options
5–39
In the following illustration, the Launch URL action has been set to execute only if a previous Message action returned “OK.”
Illustration 5-31: Launch URL Action Item
Edit Text File Options
Illustration 5-32: Edit Text File Action - Edit Text Options
VISE X User’s Guide
Section 2 Building an Installer
5–40
Action Options
Option
Description
Confirm Edit File
Before the Edit Text action takes place on the item(s)
found using the settings in What to Edit, the user is
asked to confirm the action. If Find Multiple
Occurrences is also checked, the confirmation is
effective for all items found. The text for the
confirmation message can be entered in the User
Prompt text field.
Display Found Items
Display Found Items can only be checked on if
Corfirm Edit File is also checked on. When both are
on, during an install the user will be presented with a
list containing item(s) found using the settings in What
to Edit. The items selected by the user in the list will
then be edited. The text for the confirmation message
can be entered in the User Prompt text field.
User Prompt
Text entered here will be used in the confirmation
dialog presented to the user when running the installer.
See also “Use Yes/No for Action Item Confirmations”
under “Designing the Installer’s Behavior” on
page 10-18.
Add text to the beginning
of file
Adds the text specified in the Text to Add/Append/
Replace area to the beginning of the file.
Add text to the end of
file
Adds the text specified in the Text to Add/Append/
Replace area to the end of the file.
Add a plist entry
Adds a key and its string value to the highest level of an
Apple property list file (file extension .plist), if the key
isn’t already there. Adds the key specified in the Search
For Text/Key area and the string specified in the Text to
Add/Append/Replace area.
Delete search text
Deletes the text specified in the Search for Text area.
Remove plist entry
Removes a key and its string value from any level of an
Apple property list file (file extension .plist). Removes
the key specified in the Search For Text/Key area.
Insert before search text
Inserts the text specified in the Text to Add/Append/
Replace area immediately before the text specified in the
Search For Text/Key area.
Insert after search text
Inserts the text specified in the Text to Add/Append/
Replace area immediately after the text specified in the
Search For Text/Key area.
Replace search text
Replaces the text specified in the Search For Text/Key
area with the text specified in the Add/Append/Replace
area.
Table 5-24: Edit Text File Action Options
Chapter 5 Creating Action Items
VISE X User’s Guide
Action Options
5–41
Option
Description
Replace plist entry
Replaces a key’s string value at any level of an Apple
property list file (file extension .plist). Replaces the
value of the key specified in the Search For Text/Key
area with the string specified in the Text to Add/
Append/Replace area.
Read text to variable
Reads the first 255 characters of the text file specified in
the What to Edit area and stores the value in the
variable specified in the Set Variable area.
Read plist entry to
variable
Reads the first 255 characters of a key’s string value at
any level of an Apple property list file (file extension
.plist). Reads the value of the key specified in the Search
For Text/Key area and stores the value in the variable
specified in the Set Variable area.
Search for Text/Key
Text in this area specifies what to edit in the text file.
Variable substitution is allowed. The maximum number
of characters is 255.
Text to Add/Append/
Replace
Text in this area specifies what to use in adding or
replacing text in the file. Variable substitution is
allowed. The maximum number of characters is 255.
Variable to assign
Click the button which reads (Click to assign) for a list
of variables. Selecting a variable from the list determines
the variable that will be set by this action item if the
Read text to variable function is selected.
Table 5-24: Edit Text File Action Options
The Edit Text File action item allows you to edit text in the data fork of plain text
Macintosh files, including hidden files. This action can perform the following edits:
Notes on the Edit Text File
Action
VISE X User’s Guide
■
Add text to the beginning or the end of the file.
■
Search for text and delete it, replace it or insert text before or after it.
■
Make entries in an Apple property list file (file extension .plist).
■
Read text to a variable.
■
Read a .plist entry to a variable.
Some things to consider when using the Edit Text File action follow:
■
This action is designed to edit plain text Macintosh files only. Using the action
to edit text files that contain formatting code—such as files of type RTF—will
cause unpredictable results.
■
The Edit Text File action does not support inserting text at the beginning or the
end of a file of type RTF. This restriction also applies to some Microsoft Word
format documents, such as those of type W8BN.
■
To search through a file for an Edit Text File action, VISE X will read the entire
file into available system memory. (This procedure does not use memory allocated to the installer.) If not enough memory is available, a 109 error will be
Section 2 Building an Installer
5–42
Action Options
returned. One workaround for such memory limitations is for the installer to
shut down running applications before it executes the Edit Text File action.
■
The Replace Search text function of the Edit Text File action item only handles
the first occurrence of its search text. To ensure that all occurrences of search
text are replaced, use a Jump action to loop back to the Edit Text File action
until it fails.
■
The Add a plist entry function of the Edit Text File action item will fail if the
new key already exists. To ensure that the installer makes your desired entry, you
can use two Edit Text File action items: one to attempt the addition, and one to
replace the existing .plist key if the first action fails.
■
The following functions of the Edit Text File action item will work at any level of
a .plist file: Remove plist entry, Replace plist entry and Read plist entry to
variable. These functions will look until they find the first occurrence of a
search item. If you need to find multiple occurrences of a search item, one
option is to repeat the Edit Text File action each time that it succeeds, by looping back to it with a Jump action.
In the following illustration, the Edit Text File action has been set to execute only if a previous Find action succeeds in locating the file Info.plist within the MyApp 1.0 application
Chapter 5 Creating Action Items
VISE X User’s Guide
Action Options
5–43
bundle. If the Find action is successful, the Edit Text File action will replace the value of
the key CFBundleName in Info.plist with the string MyApp 1.0.5.
Illustration 5-33: Edit Text File Action Item
Dock/Startup Items
Options
Illustration 5-34: Dock/Startup Items Action - Options
VISE X User’s Guide
Section 2 Building an Installer
5–44
Action Options
Option
Description
Confirm Action
Before the Dock/Startup Items action takes place on
the item(s) found using the settings in What to Add/
Remove, the user is asked to confirm the action. If Find
Multiple Occurrences is also checked, the confirmation
is effective for all items found. The text for the
confirmation message can be entered in the User
Prompt text field.
Display Found Items
Display Found Items can only be checked on if
Confirm Action is also checked on. When both are on,
during an install the user will be presented with a list
containing item(s) found using the settings in What to
Add/Remove. The items selected by the user in the list
will then be added or removed. The text for the
confirmation message can be entered in the User
Prompt text field.
User Prompt
Text entered here will be used in the confirmation
dialog presented to the user when running the installer.
See also “Use Yes/No for Action Item Confirmations”
under “Designing the Installer’s Behavior” on
page 10-18.
Add To
If checked on, the action will add items to the location
selected.
Remove From
If checked on, the action will remove items from the
location selected.
OS X Dock
If selected, the action will affect the items listed in the
Mac OS X Dock for the user running the installer.
Startup Items
If selected, the action will affect the Startup Items for
the user running the installer. Any items that the action
adds to Startup Items will open automatically when the
user logs in. Use of this option is equivalent to the user
opening System Preferences, then Accounts preferences,
and adding items to or removing items from the Startup
Items tab.
Hide on Startup
Hide on Startup can only be checked on if Startup
Items is selected as the location for adding or removing
items. With Hide on Startup turned on, any items that
the action adds to Startup Items will open automatically
when the user logs in, but remain hidden rather than
being shown in the Finder. Use of this option is
equivalent to the user opening System Preferences, then
Accounts preferences, and checking the Hide checkbox
for items in the Startup Items tab.
Table 5-25: Dock/Startup Items Action Options
Chapter 5 Creating Action Items
VISE X User’s Guide
Action Options
5–45
You can use the Dock/Startup Items action to make it easier for users to access your application after they install it. Available options for this action including adding to or removing items from either of these locations:
■
The Mac OS X Dock
■
Startup Items
The action includes built-in support for confirming changes with the user before proceeding, if you choose to do so.
Check Permissions
Options
Illustration 5-35: Check Permissions Action - Options
Option
Check <x> Level(s)
Above Found Item
Description
When checked on, the Check Permissions action will
check permissions for a folder in the hierarchy above
the found item. The included text field accepts digits
from 1-99 and determines the number of levels above
the found item that VISE X should go to perform the
Alias action. VISE X will automatically check this
option on and disable unchecking it when the item
specified in What to Check is known to be a file, rather
than a folder or bundle.
Table 5-26: Check Permissions Action Options
With the Check Permissions action, you can check whether the user has permission to
install to a specified location, and then base install decisions on the results. You can use
this action to provide alternatives when users don’t have permission to install to the primary location.
Notes on the Check
Permissions Action
VISE X User’s Guide
■
Unlike all other action items that can do searches, the Check Permissions action
does not require you to specify something in the Search Criteria area. The reason
for this exception is to allow checking permissions for a search location such as
the Applications folder in the Local Domain, in which case the Search Location
popmenu specifies the folder name for the search.
■
The options Search Locked Volumes and Find Multiple Occurrences are disabled for this action because they do not apply.
■
To check permissions for an install location such as the Selected Disk on the
Section 2 Building an Installer
5–46
Action Options
User Domain, all boxes in the Search Criteria area must be unchecked. In addition, in this instance you do not need to make a selection for File, Folder or
Bundle, as all three options will work.
In the example that follows, the Check Permissions action has been set to check whether
the user has permission to install to the Applications folder on the Local Domain. Other
action items could then be set to execute based upon the success or failure of this Check
Permissions action.
Illustration 5-36: Check Permissions Action Item
Chapter 5 Creating Action Items
VISE X User’s Guide
Action Options
5–47
For an example of basing install decisions on the results of the
Check Permissions action, see “Example of Shadowing a Folder” on
page 9-4.
Comment Options
Illustration 5-37: Comment Action - Comment Options
Option
Description
Name
Text that you enter in the Name field of a Comment
action will appear in the archive window under any
layout.
Extended Comment
The Extended Comment can be up to 255 characters
long. It is visible only when you choose Get Info for the
Comment action.
Table 5-27: Comment Action Options
You can use the Comment action item to note logic in your installer archives. This item
displays any text you would like to appear in your archive’s display. It has no effect on the
installers you build.
VISE X User’s Guide
Section 2 Building an Installer
5–48
Action Options
UNIX Script Options
Illustration 5-38: UNIX Script Action - Execute Script Options
Option
UNIX Script
Description
This text area should contain shell commands. Variable
substitution is allowed.
Table 5-28: UNIX Script Action Options
The UNIX Script action item offers a simple way to execute UNIX shell scripts from your
installer. This action supports the use of VISE X runtime variables, and is a good choice
for when you don't need to perform actions on installed items. (For access to standard
UNIX parameters such as $1, you'll need to use the more advanced method described in
“Executing UNIX Scripts From the Installer” on page 26-21.)
UNIX Script actions can be executed conditionally by selecting items in the Execute
Script If section of the UNIX Script Action window. UNIX Script action items can be set
to be included in an installer according to build directive and can be set to execute conditionally based on Gestalt, Language, Region and/or the result of another action item.
If you use variable substitution to pass a path in a UNIX Script
action, be sure to set the variable with a POSIX-based (slash-separated) path to conform to UNIX standards. One way to do this is
with a Find action set to Save as POSIX Path. See “Find Options” on
page 5-18 for more information.
In the following illustration, the UNIX Script action has been set to execute only if a previous Find action succeeds in locating a specified folder. If successful, the Find action will
store the full path to the folder in the runtime variable InstallPath. The UNIX Script
Chapter 5 Creating Action Items
VISE X User’s Guide
Action Options
5–49
action references the InstallPath variable in quotes so that the value will be substituted at
install time.
Illustration 5-39: UNIX Script Action Item
Saving an Action Item
VISE X User’s Guide
To save the action item and return to the archive window: clicking the close box in upper
left corner, or press Command-W. If Confirm Before Saving Get Info or Action Item
Changes in Preferences is checked on, you will be prompted to save the changes to the
action item.
Section 2 Building an Installer
5–50
Replace Options
Action Options
Replace Options allow you to determine the outcome of file or folder name conflicts
resulting from a move, rename, alias or copy action.
Illustration 5-40: Action Item Replace Options
The correct replace option for your install situation can be built using multiple selections
within the replace options menu. A selected item within one section will interact with a
selected item in another section. The table below describes each replace option selection.
Replace Option
If
If
If
If
Newer
Newer or Equal
Older or Equal
Older
Description
These four items in the topmost section of the
replace options popmenu determine the
comparison range between the existing item and
the new item. The type of comparison being done
(modification date, creation date or version) is
determined by the settings in the next section of
the popmenu.
If Different
If Different compares file type, creator, dates,
resource and data fork sizes, and finder flags. The
Compare Modification Dates, Compare Creation
Dates, and Compare Version options are disabled
when If Different is selected.
If Exists
When If Exists is selected the item will only be
installed if it already exists on the user’s machine.
Compare Modification Dates
Compare Creation Dates
Compare Version
Items in the compare section of the replace
options popmenu determine the type of
comparison that will be done to resolve name
conflicts between existing and new items.
Comparison can be based upon modification date,
creation date, or version.
Table 5-29: Action item Replace Options (Sheet 1 of 2)
Chapter 5 Creating Action Items
VISE X User’s Guide
Action Options
5–51
Replace Option
Description
Always
Never
Ask User
Always, Never, and Ask User supersede any
selection in the topmost section of the replace
options popmenu.
Checking Always will cause an existing item to
always be replaced if there is a conflict.
Checking Never will cause an existing item to
never be replaced if there is a conflict.
If there is a conflict and Ask User was checked, the
user will be given the opportunity to accept or
decline the item’s replacement.
Ask If False
Ask If False is a conditional ask user. If the
condition specified above was met, no user
interaction will take place. However, if the
condition was not met, a dialog will be displayed
asking the user if the item should be replaced.
Rename Existing
Rather than being replaced, the existing file will be
renamed using a.1,.2,.3, etc. naming sequence.
For example, suppose we created a Move Action
which will search for an application named
MyApp and move it to a backup folder. If there
already exists a MyApp application in that backup
folder, the pre-existing MyApp will be renamed to
MyApp.1.
Table 5-29: Action item Replace Options (Sheet 2 of 2)
When adding new files to an archive, if the file has a version number
(vers resource), the replace options for that file will be set to Replace
If Newer Version. (You can override this behavior with the Use
Replace Defaults option in the Installer Settings Advanced tab, or
with Folder Default Settings.)
Assigning External
Codes to Action Items
If extended functionality is required, some action items can be set to execute external
codes.
To assign external code to be executed by the action item:
Hold the mouse over the external code popmenu of your choice. If no custom
code has been added to the archive, then the external code popmenus will be disabled.
For step-by-step instructions on adding custom code to your archive, see Chapter
6-Assigning External Code. For instruction on writing your own external code, see
Chapter 26-Creating External Code.
Some action items have two or three options for external code execution, while
some action items have no such options. See the table below for a complete listing
VISE X User’s Guide
Section 2 Building an Installer
5–52
Action Options
of external code execution options within action items.
Action item
External Code Execution
Find Action
Before Find
After Find
Delete Action
Before Search
Before Delete
After Delete
Copy Action
Before Search
Before Copy
After Copy
Move Action
Before Search
Before Move
After Move
Rename Action
Before Search
Before Rename
After Rename
Alias Action
Before Search
Before Creating Alias
After Creating Alias
Message Action
Before Message Appears
After Message Appears
Form
Before User Input
After User Input
Set Variable Action
Before Setting Variable
After Setting Variable
Test Variable Action
Before Testing Variable
After Testing Variable
Jump Action
Does not execute external code.
Stop Action
Does not execute external code.
Sub-launch Action
Before Search
Before Sub-launch
After Sub-launch
Launch URL
Action
Before Launch URL
After Launch URL
Edit Text File
Action
Before Search
Before Edit
After Edit
Dock/Startup Items
Action
Before Search
Before Dock/Startup
After Dock/Startup
Table 5-30: Action Item External Code Execution Options (Sheet 1 of 2)
Chapter 5 Creating Action Items
VISE X User’s Guide
Identifying Action Items In the Archive Window
5–53
Action item
External Code Execution
Check Permissions
Action
Before Search
Before Check Permissions
After Check Permissions
Comment Action
Does not execute external code.
Table 5-30: Action Item External Code Execution Options (Sheet 2 of 2)
Identifying Action
Items In the Archive
Window
In the Archive Window, each kind of action item can be identified by a unique icon:
Icon
Action Item
Find Action
Delete Action
Copy Action
Move Action
Rename Action
Alias Action
Message Action
Form Action
Set Variable Action
Table 5-31: Action Item Icons (Sheet 1 of 2)
VISE X User’s Guide
Section 2 Building an Installer
5–54
Identifying Action Items In the Archive Window
Icon
Action Item
Test Variable Action
Jump Action
Stop Installation Action
Sub-launch Action
Launch URL Action
Edit Text File Action
Dock/Startup Items Action
Check Permissions Action
Comment Action
UNIX Script Action
Table 5-31: Action Item Icons (Sheet 2 of 2)
Duplicating Action
Items
If you need to create several similar action items, you might find it easier to create a single
action item and duplicate it several times than to set up each action item individually.
To duplicate an action item at the archive window:
1. Select the action item you wish to duplicate.
2. Click the Duplicate button in the Archive Window. The item will be duplicated.
3. For each new action item, change the attributes as desired.
Chapter 5 Creating Action Items
VISE X User’s Guide
Correct Placement of Action Items
Renaming Action Items
5–55
If you wish, you may change the name of an action item at the archive window.
To rename an action item in the archive window:
1. At the archive window, click the mouse to the right of the icon for the action item.
A name field will be displayed.
2. Enter the new name for the action item.
Correct Placement
of Action Items
Action items whose results affect the installation of an item in the archive must be performed before the item is installed. To ensure that an action item is performed before an
item is installed, move the action item so that it appears before the entry for the file or
folder in the archive window.
Action items who act on an item in the archive must be performed after the item is
installed. To ensure that an action item is performed after an item is installed, move the
action item so that it appears below the entry for the file or folder in the archive window.
Assigning Action
Items to Packages
VISE X User’s Guide
Like any other item in an archive, action items may be assigned to packages. By default, all
action items are part of the Easy Install package. You may add action items to other packages (so that they’ll be performed during Custom Installs) or remove them from the Easy
Install package, see Chapter 4-Creating Packages And Assigning Files.
Section 2 Building an Installer
5–56
Chapter 5 Creating Action Items
Assigning Action Items to Packages
VISE X User’s Guide
6–1
Chapter 6
Assigning External Code
If you created external code for an earlier version of VISE X, you may
need to recompile the code for use in the latest version. (The Read
Me file in the VISE X folder will specify this when required.) In this
case, be sure to use the new header files that are included with the
latest version of VISE X.
About External Code
VISE X extensively supports the addition of custom code to perform additional functions
required by your installer. This custom code can be in the following forms:
■
UNIX shell scripts saved as resource files of type ‘shsc’
■
AppleScripts saved as resource files of type ‘scpt’
■
CFPlugIns (file extension .bundle)
■
UNIX shell scripts saved as plain text files
For information on how to create custom code to use with VISE X, see Chapter 26-Creating External Code.
Overview of the steps to implement custom code in an installer:
1. Add the custom code to the installer.
2. Declare the code so that it is available in the installer.
3. Specify when the installer will call the code.
A description of each step follows.
VISE X User’s Guide
Section 2 Building an Installer
6–2
About External Code
Adding External Code to To add custom code to an installer:
an Installer
1. From the Archive menu, select Show Project Window.
2. If you want to add a resource, select the Resource Files item in the Project Window. To add a plug-in or script, select the PlugIns/Scripts item.
Illustration 6-1: Project Window Resource Files
3. Click the Add button and navigate to the resource, plug-in or script containing
your custom code.
Illustration 6-2: Select resource, plug-in or script to add to the project
4. Click the Choose button.
Chapter 6 Assigning External Code
VISE X User’s Guide
About External Code
6–3
5. A dialog appears (either Resource File or PlugIns/Scripts) showing the path to the
file containing your custom code. If you are using Build Directives you can make
these assignments here so that this custom code file will only be included in a built
installer if the build directive settings match.
Illustration 6-3: Resource File dialog
6. Click the OK button.
7. The custom code is now attached to the archive. Save the changes to your archive.
Declaring External Code After you add custom code to an installer, the next step is to declare the code to make it
available in the installer. (If you are working with resource files, you will want to have their
in an Installer
resource ID numbers handy.)
External codes will be called in the order that you declare them.
(This ordering appears in the External Code List dialog box.) When
you set up your installer to call more than one external code at a
time (after installing an item, for example), be sure to declare those
codes in the proper order.
To let the installer know it should look for custom code:
1. From the Archive menu, select External Codes... The External Code List dialog
box will be displayed.
VISE X User’s Guide
Section 2 Building an Installer
6–4
About External Code
2. Click New. The Edit External Code dialog box will be displayed. (The illustration
below shows a sample Shell Script/AppleScript entry.)
Illustration 6-4: Edit Shell Script/AppleScript
The following illustration shows a sample PlugIn/Shell Script entry.
Illustration 6-5: Edit PlugIn/Shell Script
Chapter 6 Assigning External Code
VISE X User’s Guide
About External Code
6–5
3. Enter the appropriate information for each field listed below:
Field Names
Enter
Name
The name you’ll use to identify the code. Example: “Get
Password”
RefCon
If desired, enter a 32-bit number to be passed to the external
code instance so it can identify from where it was called.
For more information about the uses of a RefCon, see
“Resource IDs and Reference Constants” on page 26-2.
Table 6-1: External Code Name and RefCon Fields
Next, complete either step 4 or step 5, according to your external code type.
4. If you want to declare a resource file of type ‘shsc’ or ‘scpt,’ click the Shell Script/
AppleScript ('shsc' or 'scpt') radio button and enter the appropriate information
for each field listed below.
Field Names
Enter
Resource Type
The resource type of your code.
Example: shsc
Resource ID
The resource ID number of the resource file. Valid numbers are
5000 to 9999, inclusive.
Table 6-2: External Code Resource Fields
OR
5. If you want to declare a CFPlugIn, or a shell script that was saved as a plain text
file, click the PlugIn/Shell Script (.bundle or text) radio button and select a file
from the popup menu. (If no selections are available, see the following note.)
Before you can declare a CFPlugIn or a shell script, you must first
add it to the installer (see “Adding External Code to an Installer” on
page 6-2). Only files that are listed in the PlugIns/Shell Scripts section of the Project window will be available to declare.
6. Click OK.
Resources imported from external resource files whose ID is within
5000 and 9999 (inclusive) will be automatically set to preload and
non-purgable.
VISE X User’s Guide
Section 2 Building an Installer
6–6
Editing External Code
Information
About External Code
To modify custom code information:
1. At the External Code List dialog box, select the code you wish to edit.
2. Click Edit. The Edit External Code dialog box will be displayed.
3. Make changes to the information as needed.
4. When finished, click OK.
Deleting External Code
Information
To delete custom code that you no longer need:
1. At the External Code List dialog box, select the code you wish to delete.
2. Click Delete.
Specifying When to Call Once you have added custom code to an installer and declared the code, the final step is
to specify when the installer should call the code.
External Code
There are three areas within an archive where custom code can be
assigned for execution during the install process:
1. Custom code can be assigned in the Installer Settings Advanced tab to be executed:
■
At Installer Initialization
■
Before Install
■
During the Event Loop
■
After Install
■
When the installer is quit
For more information about External Code and Advanced Installer Settings, see
“Assigning External Codes to an Installer” on page 10-28.
2. Custom code is assigned to files or folders through the Info dialog box and other
methods. The code may then be executed:
■
Before Install
■
After Install
For more information about file and folder options, see “Calling External Codes
Associated with an Item” on page 9-19.
3. Custom code is assigned to action items through the Info dialog box and other
methods. The options for custom code execution vary by action item. See “Assigning External Codes to Action Items” on page 5-51.
For complete information about the use of external codes, see Chapter 26-Creating External Code.
Chapter 6 Assigning External Code
VISE X User’s Guide
7–1
Chapter 7
Creating and Editing Gestalt Calls
About Gestalt Calls
Gestalt calls allow you to check for features available in the current operating system.
Gestalt calls can be assigned to an individual file or folder in the archive window detail or
in the item’s Get Info window (see Chapter 9-Setting File and Folder Options).
You can create and edit gestalt calls from within the VISE X application. VISE X contains
16 pre-defined gestalt call options which you may edit or delete. You may have no more
than 63 gestalt call options in an installer. You can delete gestalt entries which you will not
need so that you may create new ones.
The default setting is for gestalts to be checked only during an Easy Install. If you wish
gestalts to be checked during a custom install, select Check Gestalts on Custom Install in
Installer Settings/Interface tab.
Creating and
Modifying Gestalts
Gestalts are created and modified in the Edit Gestalt dialog box, displayed below:
Illustration 7-1: Edit Gestalt
VISE X User’s Guide
Section 2 Building an Installer
7–2
Creating and Modifying Gestalts
■
Name contains the name you assign to the gestalt so that you can recognize it
easily when assigning it to an item in the archive. The name may be up to 31
characters long.
■
Selector is a four-character code that is passed to the Gestalt Manager. If you are
checking for an existing selector, you must enter its unique code. (Information
about gestalt selectors can be found in Inside Macintosh or obtained from the
company whose product you are checking for.)
■
Gestalt is a pop-up used to determine how the result of the gestalt check will be
evaluated. It contains the following items:
Gestalt
Meaning
Exists
This gestalt must exist. If it does, the
Condition and Value are evaluated.
Doesn’t Exist
This gestalt must not exist.
Doesn’t Exist or…
Either this gestalt must not exist, or
the Condition and Value checks
must be true.
Table 7-1: Gestalt popmenu
■
Condition checks the returned gestalt value against the value in the value field.
Values include:
Condition
Meaning
> (Greater than)
This gestalt must exist. If it does,
the Condition and Value are
evaluated.
< (Less than)
This gestalt must exist. If it does,
the Condition and Value are
evaluated.
= (Equal to)
This gestalt must exist, and the
Condition and Value checks must
be true.
<> (Not equal to)
The returned value must not be
equal to the one in the Value field.
Bit set
The bits set in the Value field must
be set in the returned value.
Bit clear
The bits returned must not include
any of the bits in the Value field.
Table 7-2: Condition popmenu
■
Value is the hexadecimal number against which the returned value from the
gestalt call is compared. This number may contain up to 32 bits.
To set specific bits for the value field, hold down the mouse over the triangle to
the right of the Value field and select the desired bit. The correct hexadecimal num-
Chapter 7 Creating and Editing Gestalt Calls
VISE X User’s Guide
Creating a Gestalt Call
7–3
ber for the bits that are set will be displayed in the field.
To deselect a value, select it again so that a check is no longer displayed.
Creating a Gestalt
Call
Before creating a gestalt call, make sure that you’ve read “Creating and Modifying
Gestalts” on page 7-1.
To create a gestalt call:
1. In the Archive menu, select Gestalts...
2. The Gestalt List window will be displayed.
Illustration 7-2: Gestalt List
3. Click New. The Edit Gestalt window will be displayed.
Illustration 7-3: Edit Gestalt window
4. Enter the information for each field as required by your gestalt.
5. When finished, click OK to close the Edit Gestalt window and OK to close the
Gestalt List.
VISE X User’s Guide
Section 2 Building an Installer
7–4
Creating a Gestalt Call
6. The new gestalt check is now ready to be assigned to items in your archive.
Creating a Java Gestalt
Call
One of the pre-defined gestalt calls in VISE X checks for a specific Java version. You can
modify that gestalt to check for versions that are greater or less than the specified one. If
you want to do “equal to” checks for other Java versions, you can create new gestalts as
described here.
To create a Java gestalt call:
1. Convert the desired Java version to hexidecimal (base 16) format. For example:
Version 1.5.0_16 = 0x 01 05 00 10
Version 1.6.0_22 = 0x 01 06 00 16
2. Convert the number from the preceding step to decimal (base 10) format. For
example:
Version 1.5.0_16 = 0x1050010 = 17104912
Version 1.6.0_22 = 0x1060016 = 17170454
3. In VISE X, create a gestalt call.
4. In the Edit Gestalt window, do the following:
■
Enter a name.
■
For Selector, enter: JAVA
■
Change the Gestalt and Condition settings, if desired.
■
In the Value field, enter the decimal value from Step 2.
Illustration 7-4: Edit Gestalt window
5. Click OK to close the Edit Gestalt window and OK to close the Gestalt List.
Chapter 7 Creating and Editing Gestalt Calls
VISE X User’s Guide
8–1
Chapter 8
Setting Up Disk Information
VISE X allows you to name the disk images or folders that contain the installation sets (if
using one of these build options).
You may name the first disk image/folder and segment in the series and have VISE X
append the correct number to the rest of the disk images/folders and segments. A caret (^)
is used to request auto-incrementing, For example, if you name your disk image “Install
Disk ^,” then the first disk image will be named Install Disk 1, the second will be named
Install Disk 2, and so on.
Setting Up Disk
Information
To set up disk information for disk image or folder format installers that
will require multiple segments:
1. From the Archive menu, select Disk Names... The Disk Name List window will be
displayed.
2. Select Disk ^.
3. Click Edit. The Edit Disk Name window will be displayed:
Illustration 8-1: Edit Disk Name
4. In the Disk Name field, delete “Disk ^” and type the name you wish to assign to
the first disk image or folder. If you wish to use auto-incrementing, append a “^” to
the end of the name (for example, “Install Disk ^”).
VISE X User’s Guide
Section 2 Building an Installer
8–2
Setting Up Disk Information
5. In the Segment Name field, delete “Segment.^” and type the name you wish to
assign to the first segment. If you wish to use auto-incrementing, append a “^” to
the end of the name (for example, “Segment ^”).
If the Segment Name field is left blank, the segments will automatically be named
“Segment.1” on the first disk image or folder, “Segment.2” on the second disk
image or folder, and so on.
6. In the Disk Size field, enter the maximum size in megabytes that your segments
should be.
7. Hold down the mouse over the popmenu for Segment Size and select the size you
wish each segment to be. To create segments at the maximum disk size, you may
select Custom and enter the same size used for Disk Size, or you may select Fill
Disk, which writes the maximum amount of data for each segment.
8. When finished, click OK.
Chapter 8 Setting Up Disk Information
VISE X User’s Guide
9–1
Chapter 9
Setting File and Folder Options
Changing File and
Folder Options
VISE X User’s Guide
VISE X allows you to set several options for each file and folder included in an archive.
The characteristics that you may change for a file and folder are slightly different. Available options include the following:
■
Assigning new file types and creators.
■
Evaluating the result of a Find action item and installing or not installing the file
or folder based on the result.
■
Choosing a location where the item should be installed.
■
Assigning replacement instructions in case of a pre-existing item.
■
Assigning gestalts to be evaluated.
■
Assigning custom code to be called before or after the file is installed.
■
Choosing whether a file should be uncompressed and if so, on which installer
disk the uncompressed file should be located.
■
Determining whether the item is opened or launched when the installer is finished.
■
Selecting whether the computer should be restarted after installing this item.
■
Assigning an application and its required support files to be installed as an application package.
■
Assigning group and permissions to the item.
■
Setting the owner of the installed item to the root user.
Section 2 Building an Installer
9–2
Setting File and Folder Options
Setting File and
Folder Options
File and folder options can be changed directly in the Archive Window Detail, or in the
VISE X Get Info window for a particular file or folder.
Using the Archive
Window
To change options for a file or folder at the Archive Window:
1. Select the file or folder in the Archive Window Item List whose options you wish
to change. The Archive Window Detail will update to reflect the current attribute
values for the item
2. In the Archive Window Detail area, hold down the mouse over the appropriate
popmenu and select the desired option, as described in the next sections.
Illustration 9-1: Changing Item Options in Archive Window Detail
Using the Get Info
Window
To change options for a file or folder at the VISE X Get Info window for
that file or folder:
1. At the archive window, select the file or folder whose options you wish to change.
Chapter 9 Setting File and Folder Options
VISE X User’s Guide
Shadow Items
9–3
2. Click Get Info, press Command-I, or double-click the item. Depending on
whether the item was a file or folder, a window similar to one of these displayed
will be visible.
Illustration 9-2: Get Info Window for a File and a Folder
3. Select options as described in the next sections.
4. To return to the archive window, click the close button in the upper left corner or
press Command-W. If you haven’t saved your changes, you’ll be prompted to do
so unless you have turned off this warning in Preferences.
Shadow Items
Shadow Items are duplicates of original archive items. What makes shadow items powerful
install components is the fact that shadow items can have different options than the originals, yet they do not take up more size in the archive. Shadow items allow install options
without adding to installer size.
To create a shadow item:
1. Select the original item in the Archive Window Item List.
2. Click the Duplicate button at the top of the Archive window.
3. A duplicate, or shadow, item will be created directly below the original in the item
list. The shadow item name will be in italic as a visual indicator.
4. Set options for the shadow that are independent of the original. A shadow item can
have different Install If, Install To, Gestalt, Package assignment, Replace options,
etc.
VISE X User’s Guide
Section 2 Building an Installer
9–4
Example of Shadowing
a File
Shadow Items
In the following example, a message action is used to display a dialog to the user at install
time. The user will be able to click one of two buttons.
Illustration 9-3: Message dialog
In the VCT, the Multimedia Plug-in item is set to install to the Applications folder on the
Local Domain if no existing copy of the file is found. Otherwise, if an existing copy of
Multimedia Plug-in is found, two shadows of the Multimedia Plug-in item will determine
whether the install item replaces or renames the existing copy. The first shadow is set to
install Multimedia Plug-in and rename the existing file if the user selected Rename in the
message dialog. The second shadow is set to install Multimedia Plug-in and replace the
existing file if the user selected Replace in the message dialog.
Illustration 9-4: Shadow Items with Options Different from Original
Example of Shadowing
a Folder
The following example demonstrates how to check the user’s permissions and then install
a folder to one of two locations based on the results.
In the VCT, the MyApp 1.0 Folder item and its entire contents are set to install to the
Applications folder on the Local Domain if the user has permission to install there. Otherwise, if the user does not have permission to install to the primary location, a shadow of
Chapter 9 Setting File and Folder Options
VISE X User’s Guide
Shadow Items
9–5
the MyApp 1.0 Folder item enables installing the folder and its contents to the Applications folder on the User Domain.
Illustration 9-5: Shadow Items with Options Different from Original
Notes on Shadow Items There are several factors to consider when using shadow items in an installer:
Notes Specific to Folders
■
Shadows can be created for any original files and folders in an archive. (Duplicates of action items are not shadows.)
■
Items that have been shadowed cannot be installed to an NT volume unless the
user has Admin privileges.
■
Shadows should always be after (below) the original item in an archive.
Builder Notes
■
The following statements apply to shadow folders:
■
A twist down triangle will not be shown.
■
You cannot add items to the folder.
■
You cannot set up folder defaults. (See “Folder Default Settings” on
page 9-23.)
■
If you duplicate an application bundle, the shadow retains the same icon as the
original bundle.
■
Shadowing folders whose contents are split between multiple disks is not recommended.
Installer Notes
■
VISE X User’s Guide
To create a shadow folder, the installer extracts the contents of the folder to a
temporary location. The installer then copies those contents from the temporary
location to the install location of the shadow folder.
Section 2 Building an Installer
9–6
Item Options
■
If the user cancels the installation process after a shadow folder has been
installed, it is likely that the folder will not be deleted at the cleanup stage of the
cancelled installation.
■
Shadow folders affect the installer’s calculations of disk space requirements. For
example, if the VCT includes a shadow of one folder, the installer’s disk space
calculations will be approximately three times the size of the original folder.
These calculations account for the install sizes of the original folder, the
extracted folder in the temporary location and the shadow folder.
■
An installer will include all install items, both original and shadow items, in the
“Items to be installed” count. For example, if a VCT includes shadow folders and
is set up as follows, the install count will show 900, regardless of what folders are
installed based on specific gestalts or settings:
■
■
Original Folder (300 items)
■
Shadow Folder 1 (300 items)
■
Shadow Folder 2 (300 items)
When a folder and its shadow include action items, the installer will evaluate the
actions when installing the original folder only. It will not reevaluate action items
when installing the shadow folder. As a result, if the installer does not install the
original folder, it will be unable to install the shadow folder because it has not
evaluated required action items.
Item Options
The item options described in this section can be changed at the VISE X Get Info window
and in the Archive Window Detail if the field has been included in the current Archive
Window Layout. Each item below contains information about whether the option is available for files, for folders, or for both kinds of objects.
Changing an Item’s
Long Name
You can use the Long Name to assign the item a name of up to 255 characters. VISE X
will then use the Long Name when installing the item on Mac OS X. The original file or
folder name on your source disk will not change.
Changing a File’s
Language
If you wish the file or folder to be installed based on a language check, hold down the
mouse over the Language popmenu. During installation, if the user’s computer is not of
the language specified, the item will not be installed.
If you wish language and region checks to be in effect for files and
folders in custom packages be sure to select Check Item Gestalts On
Custom Install in Installer Settings Interface tab. For custom packages (non-Easy Install) language and region checks are not performed
unless Check Item Gestalts On Custom Install is on.
Changing a File’s Region If you wish the file or folder to be installed based on a region check, hold down the
mouse over the Region popmenu. During installation, if the user’s computer is not of the
region specified, the item will not be installed.
Chapter 9 Setting File and Folder Options
VISE X User’s Guide
Item Options
9–7
When there are check marks on items in both the Language and the
Region popmenus it represents an AND condition. Multiple check
marks within one popmenu act as an OR condition.
Changing a File’s Type
You may use the Type field to assign a new type to a file in the archive. The original file
on your source disk is not changed, but the installed version from the archive will be of
the new file type.
The default setting in this field is the original file type. To modify the file type, enter the
four-character string for the new file type in the Type field.
Changing a File’s
Creator
You may use the Creator field to assign a new creator to a file in the archive. The original
on your source disk is not changed, but the installed version from the archive will belong
to the new file creator.
The default setting in this field is the original file creator. To modify the file creator, enter
the four-character string for the new file creator in the Creator field.
Installing the Item
The Install If option lets you choose to install or not install the selected item based on the
Based on an Action Item result of a an action item.
To use the Install If options:
1. To the right of Install If click in the space labeled (Click to Assign). The Select
Action Item window will be displayed.
2. Click the name of the action item you wish to use and click Select. The name of
the selected action item will be displayed in the space next to Install If.
3. If you want the item to be installed if the action succeeds, make sure that Succeeds
is displayed in the popmenu at the right of the action item’s name.
If you want the item to be installed if the action fails, select Fails from the popmenu at the right of the action item’s name.
If the selected action is a message action the popmenu choices will be the button
titles for the message dialog.
Install To Location
VISE X User’s Guide
The Install To popmenu lets you choose the location where the item will be installed. (The
available install locations will vary depending on the selected domain. See “Domain Loca-
Section 2 Building an Installer
9–8
Item Options
tion” on page 9-9.) To assign a location, hold down the mouse over the popmenu to the
right of Install To and select from the following options:
Illustration 9-6: User Domain Install To Locations
The Search Location popmenu for User Domain is shown in the preceding illustration.
(User Domain is the default Domain setting for action items that include Search Location
and Install To popmenus.) A number of additional items may also appear in this popmenu, depending on your setup. For complete instructions on how to add or remove
these extended locations, see Chapter 29-Install Locations.
Some locations do not exist under older Mac OS versions. If you
plan to use a location that is not supported on an OS version your
customers may be using, you should create a gestalt check to ensure
that these locations exist, or deselect the Stop Install if “<type of
action>“ Fails item at the top of the Action Item window.
Chapter 9 Setting File and Folder Options
VISE X User’s Guide
Item Options
9–9
Install To:
Location
Install Folder
Installs the item in the same folder as it was located in your
archive.
Other…
Allows you to select another location for the item to be
installed. If the item is a file and you choose a file as the target
location, the file’s resources and data fork will be merged with
the file you choose (to retain the intended install location, your
source and target files must have different names). If the selected
item is a file or a folder and you choose a folder as the target
location, the file or folder will be installed inside the folder you
choose.
Variable
“InstallVar”
Installs the item in the location stored in a special VISE X
runtime variable. This allows you to dynamically set install
locations at the time of install. For more information, see
“Setting Install Locations With Variables” on page 29-4.
Ask User
Prompts the customer to identify the location on the system
where the item should be installed. A Standard Put File dialog
box will be displayed; if the customer clicks Cancel at the dialog
box, they’ll be asked if they wish to cancel the entire installation.
Find Action
Result
Installs the item in the location that was the result of a predefined Find action item.
Root of Startup
Disk
Installs the item in the root folder of the startup volume.
Table 9-1: Install To Locations
Domain Location
Because a user’s access to an install location may vary by the domain in use (System,
Local, Network, User), VISE X offers the Domain feature. You can use domains in conjunction with install locations (which you set with the Install To popmenu) to easily
install items where they will have the desired accessibility.
When an item’s Install To option is set to a domain location — as
opposed to a location such as Install Folder or a Find Action result
— the item will be installed to the boot drive or a network drive,
rather than the location the user selected. For example, a file with its
install location set to User Domain:Documents will be installed to
that location on the boot drive, regardless of what the user selected.
(For information on setting the navigation options presented to a
user at the beginning of an install, see “Setting Options for User Navigation” on
page 10-3.)
Setting a Domain for
Archive Items
VISE X User’s Guide
Your options for setting a domain are:
■
System Domain
■
Local Domain
Section 2 Building an Installer
9–10
Item Options
■
Network Domain
■
User Domain
■
Classic Domain (This domain enables installers launched on Mac OS X to install
files to the Classic environment.)
The available install locations will vary depending on the domain you have selected.
Archive Items That
Support the Domain
Setting
You can set a domain for any of these archive items:
■
File or Folder Info (defaults to User Domain)
Illustration 9-7: File Info showing Domain setting
Chapter 9 Setting File and Folder Options
VISE X User’s Guide
Item Options
9–11
■
Folder Defaults (these settings apply to entire folder contents)
Illustration 9-8: Folder Defaults showing Domain setting
■
Action items that do searches (Find, Delete, Copy, Move, Rename, Alias, Sublaunch, Edit Text File, Dock/Startup Items and Check Permissions). These
actions default to the User Domain setting.
Illustration 9-9: Delete Action showing Domain setting
VISE X User’s Guide
Section 2 Building an Installer
9–12
Item Options
■
Action items that copy or move a file or folder to a new location (Copy, Move
and Alias). These actions support setting a domain in two places: one for the
search location, and one for the copy, move or alias location. The default for
both settings is the User Domain.
Illustration 9-10: Copy Action showing Domain setting
Merging A File’s
Resources and Data Into
Another File
If desired, you may merge the resources and data of a file in the archive into the resources
and data of another file in the archive using the Other... option in the Install To: popmenu. Complete information about this topic can be found in the section “Merging
Files” on page 9-13.
Installing the Item to the
Location of a Find Action
Result
You may choose to install an item to the location that was the result of a pre-defined Find
action item. In this case, the selected item in the archive will be installed in the same
folder as the item located by the Find action item.
To install the file or folder in the archive to the same location on the target system as the item located by a Find action:
1. From the Install To popmenu, select Find Action Result... The Select Find Action
window will be displayed.
2. Click the name of the desired Find action item.
Chapter 9 Setting File and Folder Options
VISE X User’s Guide
Item Options
9–13
3. Click Select. You’ll return to the archive window or the Get Info window, with the
name of the selected Find action item displayed in the popmenu.
By default, if all the files in a folder are installed to a different location than the folder itself, the folder will not be created. (For example, if you have a folder that contains only fonts, and the fonts are all
installed to the Fonts folder, then the folder that contained the fonts
will not be created.) However, you may use the Install Empty Folders option in the Installer Settings/Behavior tab to force the installation of empty folders.
Merging Files
By using the Other... option in the Install To popmenu, you may merge the resources and
data of a file in the archive with another file in the archive, or you may merge a file in the
archive with a file that already exists on the customer’s system, located as the result of a
Find action item.
During the merge process, resources in the source file's resource fork are merged into the
destination file's resource fork. Data in the source file's data fork is appended onto the
end of the destination file's data fork.
Sample usage of this feature includes building an application on-the-fly based on the configuration of the target system.
To merge the resources and data of a file with another file in the archive or to a file
located by a Find action item, follow these steps:
1. Make sure that the source file to be merged (the one that is currently selected)
appears in the archive window after the destination target file in the archive (the
one that will receive the resources and data) or the Find action item that locates the
target file on the customer’s system.
When merging the resources and data of one file with another, the
two files must use different names. Otherwise, the target file will not
reside at the intended install location following the merge.
2. In the Install To popmenu, select Other... The Select Destination window will be
displayed, listing the names of all the files, folders, and Find action items in the
archive.
3. Click the name of the target file with which you want to merge the current file’s
resources and data or the name of the Find action item whose result on the customer’s system is the target location for the file’s resources and data.
4. Click Select. You’ll return to the archive window or the Get Info window, with the
name of the target file or action item displayed in the Install To popmenu.
Installing a File or
If desired, you may install a file or folder in the archive within another folder in the
Folder To Another Folder archive that you specify. Even though the item isn’t contained within the folder in the
archive, it will be installed to the folder when the installer is run. To install a file or folder
in the Archive
within another folder in the archive, follow these steps:
VISE X User’s Guide
Section 2 Building an Installer
9–14
Item Options
1. Make sure that the file or folder you wish to install within a folder (the one that’s
currently selected) appears in the archive window after the destination folder.
2. In the Install To popmenu, select Other... The Select Destination window will be
displayed, listing the names of all the files, folders and action items in the archive.
(If the item you selected is a folder, only the names of folders in the archive will be
displayed.)
3. Click the name of the folder where you want the selected item to be installed.
4. Click Select. You’ll return to the archive window or the Get Info window, with the
name of the target folder displayed in the Install To: popmenu.
Replacing Existing
Items on the Target
System
This option is available at the archive window or the Get Info window for both files and
folders.
Setting Replace options for a folder won’t affect the folder itself;
instead, the Replace settings selected for a folder will be applied to all
the files that are contained within the folder.
The Replace popmenu lets you determine the circumstance under which an existing file
will be replaced if a version of the file being installed is already on the target system. By
default, these settings use the modification date of the item.
To choose replacement options, hold down the mouse over the popmenu to the right of
Replace and select from the following list:
Illustration 9-11: Replace Popmenu
Chapter 9 Setting File and Folder Options
VISE X User’s Guide
Item Options
9–15
Replace Option
Description
replaces an item if the item in the archive
is newer than the item on the target
system. This is the default setting.
If Newer
If Newer or Equal
If Older or Equal
replaces an item if the item in the archive
is newer or equal to the item on the target
system.
replaces an item if the item in the archive
is older or equal to the item on the target
system.
replaces an item if the item in the archive
is older than the item on the target system.
If Older
If Different
replaces an item if the item on the archive
has a different creation date, modification
date, file size, file type, or file creator than
the item on the target system. (The
contents of the item are not evaluated.)
installs the item from the archive only if
the item exists on the target and the
modification date of the item in the
archive is newer than the one on the target
system.
If Exists
Compare Modification Dates
forces the comparison above to be based
upon modification dates of the files.
Compare Creation Dates
forces the comparison above to be based
upon the creation dates of the files.
Compare Version
forces the comparison above to be based
upon the version of the files.
Always
replaces the item on the target system with
the item in the archive.
Never
Ask User
never replaces an existing item on the
target system, installs the item only if the
item does not exist on the target system.
installs the item if it does not already exist.
If the item does exist, a dialog box is
displayed allowing the customer to choose
whether to install the item in question.
Table 9-2: Replace Options (Sheet 1 of 2)
VISE X User’s Guide
Section 2 Building an Installer
9–16
Item Options
Replace Option
Ask If False
Rename Existing
Description
is selected in addition to an item above the
separator line in the popmenu. If the item
above the separator line fails (e.g., “If
Newer” is selected but the item in the
archive is older), the customer is given the
option to install the file in the archive
anyway. This option applies to all Replace
flags except “Always” and “Ask User.”
when a conflict situation arises the existing
file will be renamed rather than replaced.
Table 9-2: Replace Options (Sheet 2 of 2)
Assigning Build
Directives to Files and
Folders
Build Directives can be set for a file or folder either from the Get Info window or from
the Archive Window detail if the Build Directive field has been included in the current
layout. The Standard archive layout contains the Build Directive popmenu and you can
add it to any custom layout.
To assign a build directive to a file or folder:
1. If you want to limit the inclusion of a file or folder to specific installer builds, with
the item selected in the archive window item list, hold down the mouse over the
Build Directives popmenu.
Build Directives serve as limiting agents for archive items. If no build directives are
checked, the inclusion of the file or folder in an installer build will not be limited.
Another way to say the same thing would be that if no items are checked in the
Build Directive popmenu, this item will always be included when an installer is
built.
Illustration 9-12: Setting Build Directives for a file
The Build Directives popmenu will display any build directive that has been set up
in the Build Directive window as well as the Any Match item.
If only one build directive item is checked, as in the example below, this item will
be included in the built installer only when that build directive is in effect.
Checking multiple items in the Build Directive popmenu will result in an AND
condition. In the example below, this item will be included in the installer when
Chapter 9 Setting File and Folder Options
VISE X User’s Guide
Item Options
9–17
the Debug Build AND the English Release build directives are in effect.
The Any Match item causes an OR condition to be in effect for any other checked
items.
In the example below, this item will be included in the installer when Debug Build
OR English Release is in effect.
If Any Match is the only item checked in the Build Directive popmenu, this file or
folder will never be included when an installer is built.
If no items are checked in the Build Directive popmenu, this file or folder will
always be included when an installer is built.
Any item in the Archive Window item list including action items,
files and folders, which has no build directives specified will always
be included in the built installer.
Storing the Item
This option is available at the archive window or the Get Info window for both files and
Uncompressed in a Disk folders.
Image or Folder
For Disk Images or Folders The Disk popmenu lets you specify which disk image or folder in the installer set will contain the item. The default setting is In Archive, which places the compressed items in the
archive. If you specify a certain disk image or folder to contain the item, it will be placed
uncompressed on that disk image or folder when the installer is built. (There is no way to
place a compressed file on a specific disk image or folder.)
To assign an item to be stored uncompressed on a specific disk image or folder, hold
down the mouse over the popmenu to the right of Disk and select the name.
By default, an installation will fail if the uncompressed file is not
found on a disk image or folder. However, you can set the installer
to succeed if uncompressed files are missing by selecting Uncompressed Files are Optional in Installer Settings/Behavior tab.
VISE X User’s Guide
Section 2 Building an Installer
9–18
For CD Installations
Item Options
By default, all the files in an archive for a CD installation will be uncompressed when you
build the installer. However, you may specify that you only want certain files to be
uncompressed. In this case, only the files that you specify to be uncompressed will be
uncompressed, and the rest of the files in the archive will be compressed, even though you
didn’t change any settings for them.
To specify that certain files be uncompressed for a CD installation:
1. Set up the archive for a CD installation as described in Chapter 15-Creating CD
Installers.
2. Select the item(s) that you want to store uncompressed on the CD.
3. In the archive window detail or in the item’s Get Info window, select the name of
the CD that you entered when you set up your disk names from the Disk: popmenu.
By assigning a specific item or items to be uncompressed, all the other items whose Disk:
options are still set to “In Archive” will be compressed in the built installer on the CD.
For more information on building CD installers, see Chapter 15-Creating CD Installers.
Installing the Item
Based On a Gestalt
Check
This option is available at the archive window or the Get Info window for files, folders,
and action items.
The Gestalt popmenu lets you select the gestalt calls that will be made to evaluate the target system.
Illustration 9-13: Gestalt popmenu contents
Gestalt evaluations assigned to a file can not be overridden by the customer. To assign a
gestalt, hold down the mouse over the popmenu to the right of Gestalt and select the
desired gestalt(s) from the list.
Chapter 9 Setting File and Folder Options
VISE X User’s Guide
Item Options
Gestalts and Any Match
9–19
The Any Match item causes an OR condition to be in effect for any other checked items.
Illustration 9-14: Gestalt menu with Any Match checked
If the requirements of the gestalt call(s) are not met for a file, the file will not be installed
during Easy Install. If a folder has a gestalt which fails, the entire folder will not be
installed. If an action item has a gestalt which fails, the action will not be executed.
By default, gestalts are only evaluated during an Easy Install. To evaluate gestalts during
Custom Install, select “Check Item Gestalts on Custom Install” in Installer Settings/Interface tab. For more information, see “Custom Install Options” on page 10-9.
Gestalt calls that are assigned here only determine whether that particular item will be
installed or executed. To evaluate minimum install requirements for an entire installation,
use the options available in the Installer Settings/Attributes tab. For information about
creating gestalt calls, see Chapter 7-Creating and Editing Gestalt Calls.
Assigning an Item to
Packages
This option is available in the archive window detail, archive window columns, or the Get
Info window for files, folders and action items.
The Packages popmenu lets you assign the selected item to packages. To assign the item to
a package, hold down the mouse over the popmenu and select the name of the desired
package.
For complete information about working with packages, see Chapter 4-Creating Packages
And Assigning Files.
Calling External Codes
Associated with an Item
Calling External Codes
Before Installing the Item
This option is available in the archive window detail, archive window columns, or the Get
Info window for files, folders, and action items.
The Before Installing popmenu lets you assign custom codes to be called before installing
the file or folder. To select a custom code, hold down the mouse over the popmenu to the
right of Before Installing: and select the name of the code. You may assign as many codes
as you wish.
For information about creating custom code, see Chapter 26-Creating External Code.
Action Items have additional options for executing external codes. See Chapter 5-Creating
Action Items.
VISE X User’s Guide
Section 2 Building an Installer
9–20
Calling External Code
After Installing the Item
Item Options
This option is available in the archive window detail, archive window columns, or the Get
Info window for files, folders, and action items.
The After Installing popmenu lets you assign custom codes to be called after installing the
file or folder. To select a custom code, hold down the mouse over the popmenu to the
right of After Installing: and select the name of the code. You may assign as many codes as
you wish.
Calling External Code
When Uninstalling the
Item
VISE X can call external code when it installs or uninstalls an item. This feature is active
for every item that calls external code. Whether your installer calls external code before or
after it installs an item, the uninstaller will follow that order when it removes the item.
Open After Installing
This option is available for files (including applications) and folders.
To launch the application after the customer quits the installer, select Open After
Installing. This item is not selected by default.
■
If the Finder was shut down during the installation, the installer will attempt to
relaunch the Finder so that it can launch the application. To ensure that the
Finder is not shut down during installation, select Don’t Quit Finder During
Install from Installer Settings/Behavior tab.
■
If you select this option for more than one item, only the first application that
was installed with this item selected will be launched.
To open the folder after the installation is complete, select Open After Installing. This
item is not selected by default.
Deleting the Item During If this file or folder should be deleted if the customer chooses to uninstall the software,
make sure Delete on Uninstalls is selected in the Get Info window. (By default, this is
Uninstalls
selected for every item set to Install Folder.)
If the file or folder should not be deleted if the customer chooses to uninstall the software, deselect Delete on Uninstalls.
In order to delete an empty folder on Mac OS X, an uninstaller will
attempt to remove the .DS_Store file if present.
Restarting After
Installing an Item
The Restart After Installing option lets you choose to restart the machine when the
installation is complete if the file is being installed to the boot drive.
A Contextual Menu item will default to Restart After Installing. If
this is the only install item set to recommend a restart, the installer
will automatically load the Contextual Menu after installing it, and
not require a restart. This convenient feature can help your customers start using your software as soon as it’s installed.
Chapter 9 Setting File and Folder Options
VISE X User’s Guide
Item Options
9–21
Turning on the package restart flag will always ask for a restart if that
package is selected unless no files were installed.
Don't Install Folder
(Placeholder)
Synchronizing Dates
The Don’t Install Folder (Placeholder) option lets you identify a folder in your archive
as an organizational container only. This setting will override the Install Empty Folders
checkbox of Installer Settings.
■
If the Don’t Install Folder (Placeholder) option is unchecked for an empty
folder (whether empty because it contains no items or because all of its items are
installed elsewhere), that folder will be installed according to the Install Empty
Folders Advanced Setting. For more information on this advanced setting, see
“Miscellaneous Behavior Settings” on page 10-20.
■
If the Don’t Install Folder (Placeholder) option is checked for a folder
(regardless of whether the folder contains any items), that folder will NOT be
installed.
VISE X can synchronize the dates of specified install items at build time, according to the
target used.
To enable synchronization for a file or folder, select Synchronize Dates in its Get Info
window. For information on setting up build targets to synchronize dates, see “Dates tab”
on page 21-16.
Installing Application
Bundles on Mac OS X
On Mac OS X, applications may be packaged as bundles. These bundles appear in the
Finder as a single file and keep applications and their required support files together. (For
information on creating Mac OS X bundles, please refer to current Apple documentation.)
To install application bundles with VISE X, make sure that the Application Bundle
option is set for the bundle in its Get Info window. VISE X automatically sets this option
for application bundles that you add to an archive.
To define the filename extensions that VISE X should use to recognize bundles, you can add the desired extensions to the text file
“Bundle Extensions.txt” in the VISE X Extensions folder. VISE X will
then treat folder structures with these extensions as bundles when
you add them to the archive or use them to set search criteria. The
VISE X Extensions folder is located within the builder’s application
bundle at: VISE X.app/Contents/Resources/VISE X Extensions.
Also see “How VISE X Checks For Bundle Version” on page 5-16.
VISE X User’s Guide
Section 2 Building an Installer
9–22
Including an Uninstall Function in the Installer
Including an
Uninstall Function in
the Installer
Along with the ability to include an Uninstall function in installers
as described here, VISE X can create standalone uninstallers. These
installers will allow users to properly remove software even if they no
longer have access to the original installers.
To create standalone uninstallers, follow the steps provided here for
the uninstall function, with one addition: For Step 3 under “Setting
Up Your Archive For Uninstalls” on page 9-22, you will need to also select the Create
Standalone Uninstaller check box.
See also “Creating a Standalone Uninstaller” on page 10-10.
VISE X lets you include an uninstall function directly into your installer.
If you include an uninstall function in your installer, it is available as an option in the
Packages popmenu where the customer selects Easy Install or Custom Install.
The Uninstall function performs the following operations:
■
Locates the items from the archive for which you selected Delete on Uninstall
that are installed on the customer’s system.
■
Performs all the action items for which you selected Perform on Uninstall at
the action item’s window. If you selected Stop Install if <Action> fails, then
failure of the action item will cause the uninstall function to quit.
■
If the customer has placed new items in a folder that is marked to be deleted on
an uninstall, the folder will not be removed. A message will be displayed informing the customer that the item has not been deleted.
By default, the uninstall function will only look for items in the location that the installer thinks they were installed. To remove an item
that may have been moved to another location, use a Delete action
item to identify and locate the target file. (If you think the customer
may have changed the name of the item, identify it by type, creator
and version number in the action item.)
Setting Up Your
Archive For
Uninstalls
To set up your archive to include the Uninstall function:
1. Make sure that any item that you wish to remove on uninstalls has Delete on
Uninstalls selected at the item’s Get Info window, and that any item that you
don’t wish to delete does not have Delete on Uninstalls selected.
2. Make sure that any action items that you wish to perform on uninstalls have Perform on Uninstall selected at the action item’s window.
3. In Installer Settings/Interface tab, select Show Uninstall in Installer Popmenu.
4. Click the Edit Uninstall Text… button and enter any explanatory text to be displayed when the user selects Uninstall from the Easy Install popmenu at the upper
left of the install window.
Symbolic Link
Symbolic links are a way to reference files and folders in the Mac OS X file system.
Because they refer to items by path, symbolic links are useful when the file or folder
should always exist at a specific location.
Chapter 9 Setting File and Folder Options
VISE X User’s Guide
Folder Default Settings
9–23
VISE X can properly install symbolic links on Mac OS X. To enable this feature, make sure
that the Symbolic Link option is checked for every symbolic link you add to the archive.
Locking File or Folder
Names
The Lock Name feature can help prevent undesired file and folder name changes when
multiple people will be working with an archive. Checking the Lock Name option for a
file or folder in the archive prevents changing the name of the item, and instructs the
installer to install the item with that name only. This rule applies even for localization, as
the installer will always install an item with its locked name.
Locked names affect the archive only, and are not the same as locked
files, which you also can install with VISE X. (For information on
how to make the File is Locked option available in an Archive Window Layout, see Chapter 20-Customizing the Archive Window.)
Folder Default
Settings
Folders within an archive can be set up with default settings so that whenever a new file or
folder is added to this folder, the default attributes will be assigned to the newly added
item.
To set up Folder Default Settings:
1. Open the Get Info for a folder by selecting the folder and clicking the Info button
at the top of the Archive window (or type Command-I) or by double-clicking the
folder.
Illustration 9-15: Folder Get Info window
VISE X User’s Guide
Section 2 Building an Installer
9–24
Folder Default Settings
2. In the folder’s get Info window, click the Setup Defaults button.
Illustration 9-16: Folder Default Settings
3. Make all settings changes which you wish to be default settings for all items at the
first level within the folder.
4. Click OK when done setting defaults.
5. Close the folder’s Get Info window.
To remove Folder Default Settings:
1. Open the Get Info for a folder by selecting the folder and clicking the Info button
at the top of the Archive window (or type Command-I).
2. In the folder’s get Info window, click the Setup Defaults button.
3. Click the None button.
4. Close the folder’s Get Info window.
About Folder Default
Settings
Folder Default Settings can be used before items are added to a folder so that new items
added get assigned the default settings. Folder Default Settings can also be used after folders and files are arranged in the archive so that items in the folder will all be assigned the
default settings.
Notes on Folder Default Settings functionality:
■
Assignment of default attributes functions when a file or folder is added by drag
and drop from the Finder, by using the Add button or by Bring Up To Date.
■
Folder Default Settings will not be used when dragging an existing file in the
VCT into the folder.
■
Folder Default Settings will be applied to all items one level deep (but not
deeper) within the folder when the folder’s Get Info window is closed.
■
Folder Default Settings do not apply to items nested within folders. In the example below, Folder Default Settings for Folder 1 would apply to Item 1, Item 2 and
Chapter 9 Setting File and Folder Options
VISE X User’s Guide
Setting Group and Permissions
9–25
Folder 1A but not to Item 3 and Item 4.
Setting Group and
Permissions
■
The Folder Default Install To setting will override the Always Set Install To
Install Folder setting in the Installer Settings Advanced tab.
■
The Folder Default Replace setting will override the Use Replace Defaults setting in the Installer Settings Advanced tab.
■
Folders for which Default Settings have been made are indicated by a D on their
folder icon in the Archive Window and in the Get Info window.
■
Double-clicking on a folder in the archive while holding down the ‘D’ or the ‘d’
key will bring up the default folder settings dialog for that folder.
With support for groups and permissions, VISE X lets you control user access to items
you install on Mac OS X. These options are available in the Get Info window of files and
folders, as illustrated below.
Illustration 9-17: Group and Permissions Options
A thorough description of groups and permissions is beyond the
scope of this documentation. Accordingly, the following information
focuses only on how to set these properties with VISE X.
VISE X User’s Guide
Section 2 Building an Installer
9–26
Setting Group and Permissions
Overview
Each file and folder on Mac OS X has an owner, a group and a set of permissions that
apply to the owner, members of the group and all others. With VISE X, you can manipulate these properties to control who can read, write and execute the item.
Setting Group for an
Install Item
The Group popmenu allows you to designate a group of users for the file or folder. You
may choose from one of three standard Mac OS X groups, or you may accept the group
setting of the folder in which you install the item. Your options are as follows:
Option
Description
Default
With this option, the install item will use the group setting of
the folder in which it is installed.
Wheel
The installer will assign the install item to the Wheel group.
Staff
The installer will assign the install item to the Staff group.
Admin
The installer will assign the install item to the Admin group.
Table 9-3: Group Options
Setting Permissions for
an Install Item
After you choose a group for the install item, the next step is to set permissions. For this,
you will need to note the following:
■
The owner of the item will be the person (according to the account in use) who
installs it.
■
The group for the item is determined by the forenamed Group setting.
■
Other includes anyone with access to the computer who is not the item’s owner
or a member of its group.
You may use the Permissions popmenu to set the following options:
Option
Description
Owner - r
The owner may read the install item.
Owner - w
The owner may write to the install item.
Owner - x
The owner may execute the install item.
Group - r
Members of the group may read the install item.
Group - w
Members of the group may write to the install item.
Group - x
Members of the group may execute the install item.
Other - r
Others may read the install item.
Other - w
Others may write to the install item.
Other - x
Others may execute the install item.
Table 9-4: Permissions Options
Chapter 9 Setting File and Folder Options
VISE X User’s Guide
Setting Group and Permissions
9–27
If you do not set group or permissions for an install item, VISE X
will install it with the permissions rwxrwxr-x (full access for everyone,
except Others have no write access) and a group of Staff.
Files and folders that you add to the archive will retain any preset
permissions.
Setting the Owner of an As noted above, the owner of the install item will be the person (according to the account
in use) who installs it. For instances in which the owner of the install item must be the
Install Item to Root
root user, VISE X includes a “Set Owner To Root” feature that can be set for any install
item.
To enable the feature, check Set Owner to Root. You will also need to enable Mac OS X
authentication, which is set from the Attributes tab of Installer Settings. See “Assigning
Minimum Requirements for Installation” on page 10-23 for more information.
VISE X User’s Guide
Section 2 Building an Installer
9–28
Chapter 9 Setting File and Folder Options
Setting Group and Permissions
VISE X User’s Guide
10–1
Chapter 10
Setting Installer Options
Installer Options
Installer Settings
The last step before building your final installer is to set general options for the installer,
such as the following:
■
Attaching a Read Me or multiple Read Me text files based on language.
■
Modifying settings, like forcing restarts or including a log file during the install.
■
Assigning minimum requirements for installation, including CPU and system version.
■
Activating user authentication for installs on Mac OS X.
■
Attaching external codes to the general installer, instead of to specific items in
packages.
■
Entering informational text to be displayed in the installer window when Easy
Install is selected.
■
Entering informational text to be displayed in the installer window when Uninstall is selected.
■
Attaching a custom icon to the installer.
■
Assigning Splash Screens and Background Images to the installer.
To set options for the installer in Installer Settings:
1. Make sure that your archive is set up exactly as you wish. If you have made changes
to any of the source files, update the archive before building the installer to ensure
that the new files are part of the install set. (For more information, see “Bringing
the Archive Up To Date” on page 16-1.)
VISE X User’s Guide
Section 2 Building an Installer
10–2
Designing the Interface Display
2. In the Archive menu, select Installer Settings. The Installer Settings window will
be displayed:
Illustration 10-1: Installer Settings
Designing the
Interface Display
You have many choices to choose from as you design the interface of your installer. Select
the appropriate settings. Some settings are conditional upon other selections.
Choosing the Default
Language
To choose which default language will be used for installer interface elements, hold down
the mouse over the popmenu for Language. This popmenu will display all installer language files from the VISE X Languages folder.
For more information about creating installers in different languages, see Chapter 23-Localization.
Setting the Default
Installer
By default, the Easy Install option is displayed to the customer after launching the
installer. If you wish for the Custom Install option to be displayed instead, select Custom
Install from the Default To popmenu. (A Custom Install option is not available if you
have not defined packages.)
Choosing the Installer
Interface
There are three primary Installer interface options as described in the table below:.
Option
Installer
Description
The standard installer interface. The button in the install
window will be named “Install” and progress dialogs will use
installation terminology.
Table 10-1: Installer Settings Display Interface Options
Chapter 10 Setting Installer Options
VISE X User’s Guide
Designing the Interface Display
10–3
Option
Description
Updater
The button in the install window will be named “Update” and
progress dialogs will use update terminology. There must be a
Default Install Location set before the Updater Interface can be
used.
Generic
The button in the install window will be named “Continue.” For
Generic installers there is no dialog presented when no items
were installed. The Generic interface option is designed for
installers composed of only action items or composed of actions
where Install terminology might be confusing and/or inaccurate
to the end user.
Table 10-1: Installer Settings Display Interface Options
Setting Options for User
Navigation
An installer can be designated as having one of three navigation options:.
Option
Option as Displayed in an Installer
Select Volumes Only
.
Table 10-2: Installer Settings Installer Navigation Options
VISE X User’s Guide
Section 2 Building an Installer
10–4
Designing the Interface Display
Option
Option as Displayed in an Installer
Show Select Folder
.
None
.
Table 10-2: Installer Settings Installer Navigation Options
Chapter 10 Setting Installer Options
VISE X User’s Guide
Designing the Interface Display
Choosing Interface Items
to Suppress
10–5
Under certain situations it may be advantageous to suppress installer interface items.
Suppress
Interface Element to be Suppressed
Main Window
Progress Stop
NOTE: It is the Stop button on the Progress dialog which is
suppressed, not the dialog itself.
Success
Table 10-3: Installer Settings Interface Suppress Options
VISE X User’s Guide
Section 2 Building an Installer
10–6
Suppressing the Entire
User Interface
Designing the Interface Display
As an alternative to suppressing only certain parts of the user interface as described for the
preceding “Suppress” options, you can suppress the entire interface for “silent” installs.
This might be useful for system administrators who want to push out installs without
requiring user intervention. It also offers some advantages for sub-launched installers,
which you can hide by enabling this option before you build and add the installers to the
main project.
To enable this option, select the Suppress User Interface check box.
If you suppress the user interface, do not prompt for user input. Anything in your installer logic that requires a user response will cause
the installer to hang. Another point to consider is that your customers will never see feedback from the installer. This might be an issue
during long installs (with no progress dialog), for example.
Choosing the Default
Install Location
You may set up VISE X so that it chooses a default installation location on the customer’s
system. If you allow other navigation options for the Install window, the customer may
still choose to install the items to a different location.
A Find action item created in the Installer Settings window is used to determine the
default location to install files. Click on the Interface tab and locate Install Location.
Click the Set Default Install Location... button.
Illustration 10-2: Setting the Default Install Location
Chapter 10 Setting Installer Options
VISE X User’s Guide
Designing the Interface Display
10–7
At the Default Install Location window, you may select Quit Installer if Find Fails. If
the item identified in the Search Criteria isn’t found, and Quit Installer if Find Fails is
selected, the installer will quit.
If Quit Installer if Find Fails is not selected, and the item identified in the Search Criteria isn’t found, then the installation will default to the root directory of the startup drive.
If Return Parent of Found Item is checked, the Default Install Location will be set to
the enclosing item of the file or folder identified by the Search Criteria.
When searching for bundles, installers search by the name of the executable inside the bundle (in case the end user has changed the bundle name). When checking for bundle version, installers use the
bundle version inside the .plist file in addition to the older-style 'vers'
resource. (Also see “How VISE X Checks For Bundle Version” on
page 5-16.)
After clicking OK in the Default Install Location dialog, your search criteria is summarized in the Text field below the Set Default Install Location button.
Installing to the
Applications Folder by
Default
As an alternative to setting the Default Install Location as described above, you may set
up your installers to default to the Applications folder, which is a common Mac OS X
install location. Whenever possible, the installer will default to the root level Applications
folder, which allows read access to virtually any user. Otherwise, the installer will default to
whichever Applications folder is appropriate to the user’s access privileges.
To set up your installers to default to the Applications folder:
1. From the Installer Settings window, click the Interface tab (if necessary).
2. Check the box for Use the “Applications” folder by Default and click OK.
Illustration 10-3: Installer Settings Interface tab
VISE X User’s Guide
Section 2 Building an Installer
10–8
Designing the Interface Display
The default install location for VISE X installers (when not set under
Archive>Installer Settings>Interface) is the root of the boot drive.
Adding Text for Display
During Easy Install
You may enter informational text to replace the generic text that’s displayed when the
Easy Install option is selected. To add informational text:
1. Click Edit Easy Install Text button.
2. In the box, enter the text that you wish to display. The text will appear exactly as
you type it in the box. (You may type more characters than can be displayed in the
box, but they may not be visible to the customer.)
Illustration 10-4: Edit Easy Install Text
As in the example above, you can use runtime variables in Easy Install text. The
runtime variables, represented by %VariableName%, will be replaced at runtime
with the values you set with constants or had set through the use of the Set Variable Action item. For a complete discussion of runtime variables see Chapter
22-Using Runtime Variables.
3. When finished, click OK.
Chapter 10 Setting Installer Options
VISE X User’s Guide
Designing the Interface Display
10–9
Other Easy Install Options
Option
Description
Show Sizes in
Easy Install
When selected, the amount of free space on the currently
selected drive and the amount of space required to install the
contents of the Easy Install package will be displayed in the Easy
Install window.
Display Easy
Install Package In
Progress
When selected, and the user selects Easy Install only the name
“Easy Install” will be displayed in the progress dialog. Normally,
the names of the files being installed show up in the progress
dialog.
Table 10-4: Installer Settings Easy Install Options
Custom Install Options
There are several installer options which apply to custom packages only.
Option
Description
Check Item
Gestalts On
Custom Install
When selected, gestalt, language and region settings assigned to
files and folders will be evaluated if the customer uses the
Custom Install option. This option is selected by default.
Show Easy Install
Package in
Custom Install
When selected, the installer will show the Easy Install package as
the first package available from a Custom Install.
Allow Only Single
Selections In
Custom Install
When selected, allows the customer to have only one custom
package turned on at a time from the Custom Install section.
Show “Select All”
Button In
Custom Install
When selected, a Select All button will be placed to the right of
the Easy/Custom Install popmenu when viewing custom
packages. When this button is selected, all packages are checked.
Table 10-5: Installer Settings Custom Install Options
Showing Uninstall in the If Show Uninstall In Installer Popmenu is checked, the Uninstall function is enabled
in the installer. An Uninstall menu item is added to the Easy Install/Custom Install pop
Installer Popmenu
VISE X User’s Guide
Section 2 Building an Installer
10–10
Designing the Interface Display
menu, the Install button is changed to Uninstall and the Uninstall text (if any) from
Installer Settings is displayed.
Illustration 10-5: Installer displaying Uninstall option
For more information, see “Including an Uninstall Function in the Installer” on page 9-22.
Creating a Standalone
Uninstaller
A standalone uninstaller can be useful in situations when the user no longer has access to
the original installer and its Uninstall feature.
To enable this option, select the Create Standalone Uninstaller check box. Your
installer will place a standalone uninstaller — named <installer name>_Uninstaller — at
the root of the install destination. When the user runs the uninstaller, it will display the
Uninstall text (if any) from Installer Settings. The uninstaller will delete itself after completing its job.
The “Don’t Shutdown Running Apps on Uninstall” option is available on the Behavior tab of Installer Settings, under Warnings.
Standalone uninstallers are placed on the root of the install destination. To allow that installation to work on Mac OS X v10.7, the
installers must be set up to require OS X authentication. For information on a workaround that does not require authentication, please
contact MindVision support.
In a future release, we plan to add the ability to choose the install
location for standalone uninstallers.
Chapter 10 Setting Installer Options
VISE X User’s Guide
Adding Read Me and License Agreements to the Installer
10–11
For more information, see “Including an Uninstall Function in the Installer” on page 9-22.
Adding Text for Display
During an Uninstall
You may enter informational text to replace the generic text that’s displayed when the
Uninstall option is selected. This text applies to installers that provide the Uninstall feature, and standalone uninstallers.
To add informational uninstall text:
1. Click Edit Uninstall Text… button.
2. In the box, enter the text that you wish to display. The text will appear exactly as
you type it in the box. (You may type more characters than can be displayed in the
box, but they may not be visible to the customer.)
3. When finished, click OK.
Adding Read Me and
License Agreements
to the Installer
VISE X allows you to create and attach separate Read Me files and License Agreements.
Select Installer Settings from the Archive menu. Click on the Text Files tab.
Illustration 10-6: Installer Settings Text Files tab
Supported File Extensions VISE X supports use of Read Me and License Agreement files that have the following file
extensions:
for Read Me and License
Agreement Files
■
.txt
Notes on Read Me and
License Agreement Files
VISE X User’s Guide
■
.rtf
■
.rtfd, which allows the files to include embedded graphics
■
.pdf
Some things to consider when creating Read Me and License Agreement files follow:
■
When creating Read Me and License Agreement files with embedded graphics,
you should not use Microsoft Word RTF format. The reason is that there are
compatibility issues with displaying these files from VISE X installers. If you need
to include graphics in your Read Me and License Agreement files, consider using
another text editor, such as the TextEdit application that ships with Mac OS X.
Section 2 Building an Installer
10–12
Assigning a Read Me
File
Adding Read Me and License Agreements to the Installer
■
With RTFD format, some fonts in double-byte character set languages (Japanese
or Chinese) will not map. Also, when using RFTD format with Japanese, you
should use the Osaka font.
■
When creating Read Me and License Agreement files in a double-byte character
set language (Japanese or Chinese), be sure to use fonts that are included with all
Mac OS X versions. For example, Osaka is a good font to use for Japanese
because that font is typically included with Mac OS X. (This warning does not
apply to PDF documents with embedded fonts, in which case font availability
should not be an issue.)
The Read Me file which you assign here will be the first item visible after the splash screen
when the installer is being used. (If you don’t use a splash screen, it will be the first item
visible.)
If you do not assign a Read Me file, then the Read Me button will not be visible to the
customer during installation.
Assigning the File
To assign a Read Me file:
1. Click the Add button. A standard file dialog box will be displayed.
2. Navigate the dialog box until you select the Read Me file you wish to use.
Illustration 10-7: Select Read Me Text File
3. Choose Relative to .vct or Absolute Path from the Path popmenu.
4. If you wish this Read Me to be the one used for a specific language, select the language from the Language: popmenu.
5. Click Choose. The language and pathname of the file will be displayed in the Read
Me Files scroll list.
Chapter 10 Setting Installer Options
VISE X User’s Guide
Adding Read Me and License Agreements to the Installer
10–13
6. To view the Read Me file as it will be displayed to the customer, click View.... To
Remove the file, click Remove. To select a different Read Me or to edit the Path or
Language settings, click Edit…
Attaching a License
Agreement
If you attach a license agreement in the Installer Settings Text Files tab, the user of the
installer you build will be presented with a window like the one that follows. When the
user clicks Continue, a dialog displays and requires acceptance of the license agreement
before any installation can take place.
To assign a text file as a license agreement:
1. Click Add. A standard file dialog box will be displayed.
2. Navigate the dialog box until you select the license agreement file you wish to use.
3. Choose Relative to .vct or Absolute Path from the Path popmenu.
4. If you wish this License Agreement to be the one used for a specific language, select
the language from the Language popmenu.
5. Click Choose. The language and pathname of the file will be displayed in the
License Agreement Files scroll list.
6. To view the License Agreement as it will be displayed to the customer, click View...
at the bottom of the window. To remove the file, click Remove. To select a different license agreement or to edit the Path or Language settings, click Edit….
VISE X User’s Guide
Section 2 Building an Installer
10–14
Read Me and License
Agreement Display
Options
Adding Read Me and License Agreements to the Installer
Display options for both Read Me files and License Agreements can be found in the
Installer Settings Text Files tab.
Display Option
Result
Don’t Display Lang. Popmenu
When checked, the Language popmenu for the
respective items (Read Me files or License
Agreement files) will no longer be available in the
built installer. Instead, the installer will display the
items according to the language of the operating
system. For example, an installer run on a
German operating system would display a Read
Me file assigned to the German language.
NOTE: With this option unchecked, the built
installer will allow the user to select a language for
the respective items (Read Me files or License
Agreement files) when applicable. However,
regardless of the language the user selects, installer
navigation buttons such as Print, Save and
Continue will remain in the language of the
operating system.
Force Scroll before Continue
When checked, the customer will need to scroll to
the bottom of the respective document (Read Me
File or License Agreement file) before the
Continue button will be enabled.
NOTE: If a Read Me file or a License Agreement
file ends with a graphic (rather than text), you will
need to enter a return after the graphic. Saving
the file with a return at the end will enable the
“Force Scroll before Continue” feature to work
properly.
Table 10-6: Read Me and License Agreement Files Display Options
Chapter 10 Setting Installer Options
VISE X User’s Guide
Extra Installer Options
Extra Installer
Options
10–15
The Installer Settings Extras tab has areas for setting a log file which your installer can
automatically produce during the install process, for setting up on-line registration and for
setting installer Splash Screens and Background Images.
Illustration 10-8: Setting an Installer Splash Screen in Installer Settings
Installer Log File
If Create Log File During Install is checked, the installer will produce a text log at the
location designated by the Location popmenu with a name designated in the Log File
Name text field. The Options popmenu contains replace options for log file.
To set up your installer log file:
1. Check Create Log File During Install from the Installer Settings Extras tab.
2. Select a location to which the log file can be saved from the Location popmenu.
Illustration 10-9: Log File Location
You can choose to have the log file created in the Install folder, on the root of the
hard drive, in the Installer Logs folder, or in any folder installed by the installer.
3. Type in a log file name in the Log File Name text field.
VISE X User’s Guide
Section 2 Building an Installer
10–16
Extra Installer Options
4. Set the desired log file replace options from the Options popmenu. Log file
replace options are described in the table below.
Replace
Option
Description
Always Replace
If the installer finds an identically named item at the location it
has set to save a log file, the pre-existing item will always be
replaced.
Append to
Existing
If the installer finds an identically named item at the location it
has set to save a log file, the new log file information will be
appended to the end of the pre-existing item.
Auto-suffix
If the installer finds an identically named item at the location it
has set to save a log file, the pre-existing item will be renamed
with a suffix.
Table 10-7: Log File Replace Options
On-line Registration
The on-line registration module provides a means for your users to quickly and conveniently register your product during the installation process. The end result should be a
higher percentage of users registering your product and more complete information from
the user.
To enable the on-line registration module:
1. Select Include On-line Registration Module from the Installer Settings Extras
tab.
2. Select Add to Application Menu if you wish a Registration menu item to be
added to the Installer’s application menu.
3. From the Display Registration popmenu select when in the install process you
wish the registration form to be displayed to the user.
4. From the Registration Form popmenu select which form to display for registration.
For complete information on setting up forms see Chapter 27-VISE X Forms.
For complete information on setting up the on-line registration module see Chapter 28-On-Line Registration.
Adding a Splash Screen With support for a number of popular media formats, VISE X lets you use still images,
and Background Image movies, animation and sound to add impact to your installers.
Your options for presenting images and sound in installers include the following:
■
A custom splash screen to greet the customer when your installer is launched
■
A custom background image to display throughout the install
■
Multiple billboard screens to display in the order you specify (see Chapter
11-Adding Billboards to an Installer)
Supported File Extensions VISE X supports use of Splash Screens, Background Images and Billboards that have the
following file extensions:
■
Chapter 10 Setting Installer Options
.bmp
VISE X User’s Guide
Extra Installer Options
10–17
■
.gif
■
.jpg
■
.pct
■
.png
■
.psd
■
.tif
Additionally, Splash Screens and Billboards (but not Background Images) can have the following file extensions:
Recommended Sizing
■
.avi
■
.mov
■
.mp4
■
.mpg
■
.swf
For splash screens, the image area size is 415 pixels wide by 330 pixels high. Billboards
should be 415 pixels wide by 235 pixels high, and background images should be 620 pixels
wide by 435 pixels high.
Adding a Splash Screen To add a Splash Screen:
1. In VISE X, click on the Extras Tab in the Installer Settings dialog box.
2. In the Splash Screen panel, click the Choose button. A standard file dialog box
will be displayed.
3. Navigate the dialog box until you select the Splash Screen you wish to use.
4. Click Choose. The pathname of the file will be displayed in the Splash Screen
panel.
5. If appropriate, select Scale Splash Image. (You can also select this option as part
of the following step.)
6. To view the Splash Screen file as it will be displayed to the customer, click View...
To remove the file, click Remove. To select a different Splash Screen file, click
Choose.
Adding a Background
Image
To add a Background Image:
1. In VISE X, click on the Extras Tab in the Installer Settings dialog box.
2. In the Background Images panel, click the Choose button. A standard file dialog
box will be displayed.
3. Navigate the dialog box until you select the Background Image you wish to use.
4. Click Choose. The pathname of the file will be displayed in the Background Image
panel.
5. To view the Splash Screen file as it will be displayed to the customer, click View...
To remove the file, click Remove. To select a different Background Image file, click
Choose.
VISE X User’s Guide
Section 2 Building an Installer
10–18
Designing the
Installer’s Behavior
Designing the Installer’s Behavior
You can customize the installer’s behavior including warning messages, installation destination options, and other installation choices. Select Installer Settings from the Archive
menu. Click on the Behavior tab.
Illustration 10-10: Installer Settings Behavior tab
Including or Excluding
Warnings
Option
Description
Shutdown
Applications
Before Installing
Causes all applications other than the installer to be shut down
before installation. (It does not cause the Finder to quit.)
NOTE: The “Restart after Installing” option for packages can
cause installers to shut down all running applications before
installing the package, but only if “Shutdown Applications
before Installing” is enabled here in Installer Settings. If the
package option is enabled but this Installer Settings option is
not, the installer will install the corresponding package without
shutting down applications first. See also “Edit Package options”
on page 4-8.
Don’t Shutdown
Running Apps on
Uninstall
By default, the installer will shut down applications that are
running during an uninstall. To prevent this, check Don’t
Shutdown Running Apps on Uninstall.
Force Restart
when Appropriate
When appropriate, forces the customer’s computer to restart
after installation. The customer will be warned at the beginning
of the installation that a Restart will be required, and given the
option to cancel installation at that time.
Table 10-8: Installer Settings Warning Options
Chapter 10 Setting Installer Options
VISE X User’s Guide
Designing the Installer’s Behavior
10–19
Option
Description
No Restart
Warnings
By default, the installer warns the customer if it needs to shut
down all running applications at the beginning of the install. If
you select this option, no warning message will be displayed to
the customer; the installer will automatically shut down the
running applications.
Allow Sublaunched Installer
Restart
By default, when a sub-launched installer has a flag set to restart
the customer’s computer after installation, the parent installer
will ignore that flag. To allow the restarts to occur, check Allow
Sub-launched Installer Restart.
Use Yes/No for
Action Item
Confirmations
By default, when an action item is set up so the user must
confirm the action, the user has two choices: OK or Cancel. To
change those changes to Yes or No, check Use Yes/No for
Action Item Confirmations.
Table 10-8: Installer Settings Warning Options
Choosing Installation
Destinations
Option
Description
Create
Installation Folder
Named
When selected, the installer will create a folder with the given
name and install the items on the root level of the archive in it.
Always Create
Moved Items
Folder
A Moved Items folder, called VISE Moved Items, is created in
the Cleanup At Startup folder (an invisible folder on the boot
volume disk) whenever the installer needs to move something
during an install. This Moved Items folder may then be used
from an external code. Mac OS X will delete the Cleanup at
Startup folder and its contents upon restart.
Allow Installation
To Mounted
Servers
When selected, allows the software to be installed over a network
to a remote volume. This option will not work for installations
that require file/folders to be installed into the destination
volume’s System File or Folder.
Allow Installation
to UFS Volumes
When selected, allows the software to be installed to UNIX File
System (UFS) volumes. NOTE: The two major file systems on
Mac OS X are Mac OS Extended (HFS+), the traditional
Macintosh volume format, and UFS. Most users will have their
system installed on HFS+.
Allow User To
Choose Invisible
Folders
When selected, the installer will allow users to install items to
invisible folders on Mac OS X. By default, this option is
unchecked, in which case the installer will not display invisible
folders to the user during a Mac OS X install.
Table 10-9: Installer Settings Destinations Options
VISE X User’s Guide
Section 2 Building an Installer
10–20
Designing the Installer’s Behavior
Miscellaneous Behavior
Settings
Option
Description
Don't Allow
Multiple Installs
If selected, the customer is not given the option to install
another package after a successful installation has occurred.
(However, they may quit the installer, then relaunch it and
install another package.)
Install Empty
Folders
If this setting is OFF the installer will not install an empty folder
if all of that folder’s items are installed elsewhere.
If this setting is ON the installer will install an empty folder if all
of that folder’s items are installed elsewhere.
If a folder has no items in it in the archive, this setting does not
apply. (The folder will be installed in this instance.)
NOTE: You can override this setting for individual folders in
your archive with the Don’t Install Folder (Placeholder)
option. The “placeholder” option lets you identify a folder in
your archive as an organizational container only, so that the
folder will never be installed (regardless of whether the folder
contains any items). For more information, see “Don't Install
Folder (Placeholder)” on page 9-21.
Uncompressed
Files Are
Optional
When selected and an uncompressed file is deleted from a
diskette, the installer will continue to function correctly. The
missing files will be skipped.
Modify File Date
When Merging
Resources
When resources are merged into another file, the file’s
modification date will be set to that of the merged file.
Action Items
Ignore Hidden
Items
When checked, installers will ignore hidden Mac OS X items
during searches. A file or folder with the invisible bit enabled or
a name starting with “.” will be not be valid for search results.
Also, if any parents of an item are invisible as defined here, the
item will not be valid for search results.
Force QD
Drawing Refresh
QuickDraw drawing refresh can slow down some installations, so
it is available here as an option that is turned off by default.
Leaving this option turned off will potentially improve the
performance of all installers, and in particular should help speed
up installers that deliver many small files.
Table 10-10: Installer Settings Miscellaneous Behavior Options
Chapter 10 Setting Installer Options
VISE X User’s Guide
Designing the Installer’s Behavior
Sub Launch Locks
10–21
Sub-launch Locks allow you to control which interface items will always be displayed by
your installer when it is sub-launched from another VISE X installer.
Option
Description
Splash Screen
When checked in a sub-launched installer, the Splash Screen will
always be displayed regardless of the sub-launch options set in
the parent installer’s Sub-launch Action item.
License
Agreement
When checked in a sub-launched installer, the License
Agreement will always be displayed regardless of the sub-launch
options set in the parent installer’s Sub-launch Action item.
Read Me
When checked in a sub-launched installer, the Read Me will
always be displayed regardless of the sub-launch options set in
the parent installer’s Sub-launch Action item.
Billboards
When checked in a sub-launched installer, the Billboards will
always be displayed regardless of the sub-launch options set in
the parent installer’s Sub-launch Action item.
Table 10-11: Installer Settings Sub-launch Lock Options
Sub-launch Locks in a sub-launched installer will override any sublaunch options set in the Parent Installer’s Sub-launch Action item.
For more information on the Sub-launch Action item see “Sublaunch Action Options” on page 5-35.
VISE X User’s Guide
Section 2 Building an Installer
10–22
Installer Attributes
Installer Attributes
You can customize your installer with your own installer icon, define minimum requirements for software installation, and enable password protection. Select Installer Settings
from the Archive menu. Click on the Attributes tab.
Illustration 10-11: Installer Settings Attributes tab
Assigning a Custom
Icon
You may assign a custom icon to the installer at the Installer Settings window. This
method turns on the Finder bit for a custom icon and adds the icon resources to the
installer.
VISE X supports large (128x128 pixel) icons for crisp display on
Apple’s Aqua interface (Mac OS X). This size of icon will display
properly at all available views.
To assign a custom icon to the installer at the Installer Settings window:
1. Copy the icon to the Clipboard.
2. Click in the Installer Icon box so that it is selected.
3. Press Command-V to paste the icon from the Clipboard to the window.
You can also drag and drop a file on the Install Icon dialog and it will use the icon
from that file’s bundle resource for the custom installer icon. Drag and drop is supported for Mac OS X icon (.icns) files.
To remove a custom icon, click in the box and press Command-X.
Chapter 10 Setting Installer Options
VISE X User’s Guide
Installer Attributes
Assigning Minimum
Requirements for
Installation
10–23
This area allows you to define the minimum system requirements for installing your product. Minimum requirements can be assigned in the following ways:
Option
Description
CPU
Allows selection of the minimum CPU upon which your
software can be installed. The default setting is G3.
System Version
Allows setting of the minimum version of the operating system
that your software requires. The earliest System that can be
defined is System 10.2.0 (the minimum System requirement for
VISE X installers). Use the Tab key to move between fields.
Quit Installer
if Not
Administrator
When checked on, the installer will display a message and cancel
the install if the user is not logged in as administrator.
Require OS X
Authentication
When an install to Mac OS X requires special access privileges,
VISE X can prompt the user for user name and password, and
authenticate that information before proceeding. If the user is
already logged in as administrator, the installer will simply
relaunch itself to get authentication privileges. Check this
option on to enable such authentication.
Allow User To
Override
Minimum
Requirements
When checked on, the customer will be given the option to
install the software, even if one or more of the minimum
requirements for installation outlined above have not been met.
A dialog box will be displayed that states which requirement was
not met, and allowing the customer to choose whether the
installation should continue.
Table 10-12: Installer Settings Minimum Requirements to Install
Setting an Installer
Password
VISE X allows you to set up a password for an installer and to determine when the password will be required.
Illustration 10-12: Installer Password Options
Setting a password will cause all data in your installer to be encrypted.
Auto-Validating Password
Auto-validating passwords provides a way to allow one installer to accept multiple passwords. Each customer can then be given a different password, which can be used for tracking in software piracy cases. The algorithm used in authenticating the password is by no
means foolproof, but should provide a deterrent for the average user.
To set up an auto-validating password:
VISE X User’s Guide
Section 2 Building an Installer
10–24
Installer Attributes
1. Enter a seed value in the Password field of the Installer Settings Attributes tab. The
seed value should be a number of 5 or 6 digits.
The seed value for your auto-validating password should not begin
with zero. You can use zero for any of the remaining digits, however.
2. Check the Auto-Validating Password checkbox.
3. Click the Generate button.
4. In the Generate Password dialog enter a starting value and how many passwords to
generate.
Illustration 10-13: Generate Password dialog
5. Click OK.
6. Pick a location to save the password list.
Illustration 10-14: Saving Password File
Chapter 10 Setting Installer Options
VISE X User’s Guide
Adding Advanced Features to Your Installer
10–25
7. The text file generated will contain the initial password and the list of all self-validating passwords.
Illustration 10-15: Password file
Adding Advanced
Features to Your
Installer
VISE X allows you to select various compression settings, choose whether or not to
replace existing files in an archive and add external code. Select Installer Settings from
the Archive menu. Click on the Advanced tab.
Illustration 10-16: Installer Settings Advanced Tab
VISE X User’s Guide
Section 2 Building an Installer
10–26
Adding Advanced Features to Your Installer
Compressing Files
Option
Description
Don’t
Recompress Data
When selected, data in the archive will not be recompressed
when you build the installer. This may result in larger installers.
Only Store
Catalog of Files
When this item is checked a Catalog Only installer will be
produced at build time.This item should only be used with CDROM installs where all the files to be installed will be
uncompressed. This feature creates an archive which only
contains a catalog of the files, saving the time required to
compress and decompress them. The installer is then created
using only the catalog, so the items in the archive must be
placed on the CD in the same hierarchy as they were placed in
the archive.
Don’t Copy Files
from Source at
Build Time
If this checkbox is turned on, when the installer is built, files
will not be copied from the build source to the build target. You
may want to turn this checkbox on if your build source and
build Target is the same location on your hard drive.
Table 10-13: Installer Settings Compression Options
Setting Only Store Catalog of Files for an archive is a one way street. Since an archive cannot be converted back to a standard archive of compressed files after this setting has been
saved, the warning below is displayed before the setting is saved.
Illustration 10-17: Catalog Only warning
Catalog Only archives cannot be used to build compressed installers.
When Only Store Catalog of Files is checked on, all Build Targets
which require compressed data will be automatically set to CD
Installer. For more information on Build Targets see Chapter
21-Advanced Project Management.
Chapter 10 Setting Installer Options
VISE X User’s Guide
Adding Advanced Features to Your Installer
10–27
Adding Files to an
Existing Archive
Option
Description
Update Archive
Files With Any
Difference
When selected and you update an archive, files that are different
in any way from the files already in the archive will replace the
ones in the archive.
Update Only Files
Already In The
Archive
When selected and you update an archive, only files that are
already in the archive will be evaluated during the update
process. Other files in the source folder will be ignored.
Don’t Update
Packages on
Imported VCT
Files
When selected, package assignments for embedded VCT items
will not be overridden (back to what they were in the VCT
before it was embedded) by a Bring Up To Date operation.
Ignore DS_Store
Files
When selected and you add a folder to an archive, DS_Store files
will not be imported. Also, when you update the archive
DS_Store files will never be marked to be added to the VCT as
new files.
Ignore Hidden
Files
When selected and you add a folder to an archive, hidden files
will not be imported. Also, when you update the archive hidden
files will never be marked to be added to the VCT as new files.
Use Replace
Defaults
When selected, files and folders that you add to the archive will
use the Replace options that you specified with the Replace
Defaults popmenu. (There is one exception to this behavior. For
details, see “Notes on the Use Replace Defaults Option” on
page 10-27.)
Replace Defaults
Your selection determines the default Replace options for files
and folders that you add to the archive. For more information
on Replace options, see “Replacing Existing Items on the Target
System” on page 9-14. Also see “Notes on the Use Replace
Defaults Option” on page 10-27.
Show Size in
Your selection determines whether the size of the files in the
archive will be displayed as kilobytes or as bytes.
Table 10-14: Installer Settings Builder Options
Notes on the Use Replace
Defaults Option
■
If you add items to an archive folder that uses Folder Default Settings, the
Replace options set for that folder will override your Use Replace Defaults
installer settings.
■
One way that VISE X can determine whether to replace existing items with new
ones is to compare versions. If you use the Compare Version option to make
replacement decisions based on version, make sure that all items to be compared
will have a version. The comparisons will fail if the items do not have a version.
Assigning a Localization Localization files can be attached to an archive from the Localization Window (see Chapter 23-Localization). The localization file set in the localization window will also appear in
File
Installer Settings. Assigning a localization file from Installer Settings is also an option, as
described in the following steps.
VISE X User’s Guide
Section 2 Building an Installer
10–28
Adding Advanced Features to Your Installer
To assign a localization file to your archive from Installer Settings:
1. In the Installer Settings Advanced tab, locate the Localization File section and click
the Set Localization File... button. A standard file dialog box will be displayed.
2. Navigate the dialog box until you select the item localization file you wish to use.
3. Click the Choose button. The pathname of the file will be displayed in the field.
To remove a localization file, click the Remove button.
Assigning External
Codes to an Installer
Any custom external codes which you defined can be attached to the installer as well as to
individual files.
Illustration 10-18: Installer Settings Advanced tab, External Codes
Custom external codes may be called at the following times:
■
Initialization calls the code immediately when the installer is launched, before
anything is displayed to the customer.
■
Event Loop calls the code in the main event loop, before normal processing
occurs for that event. Sample usage: To override the regular call for help.
■
Installer Quit calls the code when the installer is quit. Sample usage: To free up
memory allocated in the System Heap from another call to external code.
■
Before Install calls the code after the install button is clicked and before any
files are installed. Sample usage: To check whether certain packages are selected
before beginning an installation.
■
After Install calls the code after the installation is complete but before a dialog
box is displayed to the customer. Sample usage: To bring up a dialog box so that
the customer can register your software package.
To attach a custom code to one of these items, hold down the mouse next to the name of
the item and select the code from the pop-up.
Chapter 10 Setting Installer Options
VISE X User’s Guide
Installer Settings for Web Installers
10–29
For information about creating custom codes, see Chapter 26-Creating External Code.
Option
Description
External Code Is
Optional
By default, any external code that needs to be called must be
present in the resource fork of the installer. When selected and
external code has been deleted from the installer, the installer
will function as if no external code was assigned to the files.
Allow Installer
Resources To Be
Replaced
When selected, you may include resources in the resource fork
of the archive file that replace the installer’s own resources.
Disable Strict
Library Checking
When selected, this option prevents VISE X from performing
library checks before calling external code. This checking is
otherwise performed by default to prevent calling an
InterfaceLib-linked external code from a VISE X/Carbon
installer, or a CarbonLib external code from a PowerPC installer.
(Carbon and PowerPC installers can be created by Installer VISE
8.x only. The Disable Strict Library Checking option is retained
in VISE X to prevent calling InterfaceLib-linked external code
from VISE X installers, and for legacy purposes to facilitate the
conversion of Installer VISE 8.x installers to VISE X format.)
Table 10-15: Installer Settings External Codes Options
Installer Settings for
Web Installers
There are a number of VISE X options which apply specifically to web installers. Those
options can be found in Installer Settings Web tab. For more information on the construction and deployment of web installers, see Chapter 30-Active Web Installers.
Illustration 10-19: Installer Settings Web tab
VISE X User’s Guide
Section 2 Building an Installer
10–30
Saving Installer Settings
Option
Description
Create Separate Catalog
When checked, a separate catalog file will be
created. This catalog enables the web installer
to self update when appropriate.
Strict Installer Data Time Stamp
Checking
When turned on, the built installer will require
the time stamp of the installer and the time
stamp of the VISEICat.idx file on the Web/
FTP server to be the same. This will require the
VISEICat.idx file to be uploaded to the Web/
FTP site every time you build.
Upload Cab File(s) To Web Server
At Build Time (FTP sites only)
When turned on, VISE X will upload CAB
files to the FTP servers listed in the Download
Sites dialog. (Do not use this feature if you
have HTTP servers listed in the Download
Sites dialog.) This feature requires the servers
to have FTP “STOR” command support.
Suppress Internet Dialup Dialog
Turning this checkbox on, prevents the
installer from displaying the “Please make sure
you have an active Internet connection” dialog
to the user. You may want to turn this on if
you are assured the user will already have an
active connection.
Allow User To Choose Download
Site
When turned on, a popmenu will appear in
the “Please make sure you have an active
Internet connection” dialog, allowing the user
to choose which site to download the data
from.
Suppress Internet Disconnect
Dialog
Turning this checkbox on, prevents the
installer from displaying the “Disconnect from
the Internet now” dialog to the user.
Byte Range Downloads
When turned on, VISE X will create a single
CAB file instead of using Group File
assignments. This feature allows for the
smallest and quickest downloads possible. It
also requires the web servers to be HTTP 1.1
compliant or have FTP “REST” command
support.
Table 10-16: Installer Settings Web tab Options
Saving
Installer Settings
VISE X allows you to save your Installer Settings for use with another archive or so that
different Build Targets can have different Installer Settings.
Chapter 10 Setting Installer Options
VISE X User’s Guide
Saving Installer Settings
10–31
You can save your final selections by selecting Save Setting As... from the Settings popmenu in the lower left corner of the Installer Settings window. Enter an unique name for
the setting file. Click the Create button.
Illustration 10-20: Saving new Installer Settings
Selecting Installer
Settings
From the Settings menu at the bottom left of the Installer Settings window you can
change the Installer Settings for the current archive to any other saved archive setting.
Illustration 10-21: Selecting a Different set of Installer Settings
Defaulting Installer
Settings
You may want to designate a saved Installer Settings file as the default settings for any new
archive.
To set a default archive setting:
1. Set up and save an archive setting file as described above.
VISE X User’s Guide
Section 2 Building an Installer
10–32
Saving Installer Settings
2. Select Export Setting... from the Settings popmenu.
Illustration 10-22: Export Settings
3. Enter a name for the exported settings file.
Illustration 10-23: Exported Settings Name
4. The exported settings file will be saved in your Preferences, VISE X Settings folder.
Illustration 10-24: VISE X Settings folder
5. Select Preferences… from the Edit menu.
Chapter 10 Setting Installer Options
VISE X User’s Guide
Saving Installer Settings
10–33
6. Click the Select File… button in the Preferences window.
Illustration 10-25: VISE X Preferences
7. Select the default Installer Settings file you wish to be used for new archives created
with VISE X. Saved Installer Settings files are located at:
Illustration 10-26: Selecting the Installer Settings file for Default
Exported Installer Settings files are saved at the following path:
VISE X User’s Guide
Section 2 Building an Installer
10–34
Saving Installer Settings
■
Startup Volume:Library Folder:Preferences:VISE X Settings
Illustration 10-27: VISE X Settings
8. The name of the Installer Settings file will be displayed in the preferences window.
Any new VCTs will use this archive setting
Illustration 10-28: Preferences Displaying Default Installer Settings
Deleting Installer
Settings
You can delete Installer Settings that you have created and saved.
Chapter 10 Setting Installer Options
VISE X User’s Guide
Supporting Multiple Users Accounts
10–35
1. Select Delete Setting... from the Settings popmenu in the Installer Settings window.
Illustration 10-29: Deleting an Installer Setting
2. A dialog appears. Select the appropriate archive and click Delete.
Illustration 10-30: Select Settings To Delete
3. Click OK to close the Installer Settings window.
Supporting Multiple
Users Accounts
Multiple Users Accounts can prevent users from installing files where they shouldn’t.
VISE X supports this security feature with every installer that you build. On a system that
uses Multiple Users Accounts, VISE X will return an error if the user tries to install files
without the proper privileges.
Illustration 10-31: Macintosh Privileges Error 1
VISE X User’s Guide
Section 2 Building an Installer
10–36
Supporting Multiple Users Accounts
When the user clicks OK in the preceding error dialog, the following dialog displays.
Illustration 10-32: Macintosh Privileges Error 2
Chapter 10 Setting Installer Options
VISE X User’s Guide
11–1
Chapter 11
Adding Billboards to an Installer
Billboards
Billboards are communication tools used during the install process for purposes ranging
from highlighting software features to encouraging user registration. Billboards are one
more avenue for installer personalization.
Illustration 11-1: Billboard as Displayed During Installation
In addition to displaying multiple custom billboards during the
installation process, you have the option of displaying a custom
splash screen when the installer is launched. For more information
on splash screens, see “Adding a Splash Screen and Background
Image” on page 10-16.
VISE X User’s Guide
Section 2 Building an Installer
11–2
Supported File
Extensions
Billboard Display Method
VISE X supports use of billboards that have the following file extensions:
■
.bmp
■
.gif
■
.jpg
■
.pct
■
.png
■
.psd
■
.tif
■
.avi
■
.mov
■
.mp4
■
.mpg
■
.swf
Recommended Sizing
The image area size for billboards is 415 pixels wide by 235 pixels high.
Billboard Display
Method
Billboards can be displayed sequentially, by disk or by package.
Display Method
Explanation
Sequentially
Billboards will be displayed in sequence during
the install. Billboard duration can be set per
billboard. If billboard durations exceed actual
install time, some billboards may not be
displayed.
By Disk
Billboards will be displayed by disk during the
install. If a disk is not used during an install, the
billboard assigned to that disk will not be
displayed.
By Package
Billboards will be displayed by package as the
package is installed.
Table 11-1: Billboard Display Methods
Assigning Billboards
Billboards can be set to be displayed sequentially, by package or by disk. The default setting is to display billboards sequentially.
Chapter 11 Adding Billboards to an Installer
VISE X User’s Guide
Assigning Billboards
11–3
To set up billboards:
1. At the Archive window, select Billboards… from the Archive menu. The Billboards dialog will be displayed.
Illustration 11-2: Billboards dialog
2. From the Billboard Type popmenu, select one of the following display options:
Sequentially, By Disk or Package.
3. If you’re setting up a sequential billboard, click the New Billboard button. Otherwise, skip this step and continue with step 5.
4. In the Billboard Properties section of the Billboards window, click the Choose button.
5. A standard File dialog will be displayed. Locate and select the desired billboard
image file and then click the Choose button. The image you chose will appear
within the billboard box.
Illustration 11-3: Disk Billboards
6. If you’re setting up a sequential billboard, you have the option to enter the minimum number of seconds the billboard should display. The default is three seconds.
7. To view a preview of the billboard as it will appear in the installer, click the View
button. A preview window will display. If appropriate, select Scale Image. Then
click Continue to close the window.
VISE X User’s Guide
Section 2 Building an Installer
11–4
Assigning Billboards
8. If the billboard image is a movie, you may select the following movie options:
Option
Description
Finish playing last movie
If the last billboard displayed in an installer is a
movie, the installer will finish playing that movie
before moving on to the Finished screen.
Cache billboards on local drive
This option is available to improve the performance
of CD installers that display movie billboards. With
this option selected, installers will copy movie
billboards to the local hard drive when users click
Install. The installers will then run the movie
billboards from the local hard drive and delete the
files when the installation is complete. This option
requires enough hard drive space to cache the
movie billboards.
Table 11-2: Billboard Movie Options
9. Repeat this process to add as many billboards as desired. (You will need to click
New Billboard when adding each subsequent billboard.) Your billboard entries
should look similar to the Disk Billboards example below.
Illustration 11-4: Disk Billboards with graphics
10. To view a preview of the billboard sequence as it will appear in the installer, click
the Preview Sequence button. A preview window will display. The window will
automatically close at the end of the preview. Alternately, you can click Continue
to close the window at any time.
11. When you’re finished, click OK to close the Billboards window.
Selecting an option from the Display Billboards popmenu as
described in step 2 above will automatically set the same option for
the active build target. However, if you are using multiple build targets in your archive, you must manually set the Display Billboards
popmenu for each of the additional targets. See “Display Billboards”
on page 21-12 and “Active Build Target” on page 21-18.
Using Billboard Files
VISE X supports the use of multiple billboard sets, called billboard files. Billboard files
allow you to create different sets of billboards for different languages or even to create different sets of billboards for the same language.
Chapter 11 Adding Billboards to an Installer
VISE X User’s Guide
Assigning Billboards
11–5
Billboard files are created and configured from the Billboard dialog, Billboard File popmenu.
Illustration 11-5: Billboard dialog Billboard File popmenu
The Billboard File popmenu contains:
■
Resource of Archive - The billboards assigned to Resource of Archive are the
default billboards. This set of billboards will be used by a built installer if these
are the only billboards in the installer or if the language specific billboards do
not match the language of the Mac OS under which the installer is being run.
■
The name of any billboard file added to the Project Window. Select the billboard
file to edit the contents.
■
New Billboard File - selecting this item brings up a standard pick dialog where
an existing billboard file can be selected or a new billboard file can be created.
When a new billboard file is added from the New Billboard File item, the Project
Window is automatically opened and the newly added item is selected.
At the Project Window, Build Directives and Language can be set for billboard
Files. For more information on Billboard File settings accessed from the project
Window, see “Billboard Files” on page 21-24.
When the installer is built, all of the billboards which meet the build directive criteria are
merged into the installer. Resource IDs are renumbered to avoid conflicts. This allows a
multi-language installer to be built with language specific billboards. When the installer is
run, the billboards for the appropriate language will be displayed.
If the path to a particular billboard file cannot be resolved, then that item is grayed in the
Billboard File popmenu.
Illustration 11-6: Billboard File Item with Unresolved Path
Removing a Billboard
To remove a billboard:
1. Select Billboards… from the Archive menu. The Billboards dialog will be displayed.
VISE X User’s Guide
Section 2 Building an Installer
11–6
Assigning Billboards
2. Select the image you wish to remove and click the Edit button. The Edit Billboard
dialog is displayed. In the Edit Billboard window click the Remove button.
Illustration 11-7: Removing a Billboard
Chapter 11 Adding Billboards to an Installer
VISE X User’s Guide
12–1
Chapter 12
Generating Archive Reports
Before creating a final installer, you can generate different kinds of reports to anticipate
problems that may arise.
Archive Reports
To generate an archive report for the current archive:
1. From the File menu select Page Setup.
Archive Reports (whether to Printer, Text File or Screen) will use the
current Archive Window layout selection of columns.
For some Archive Window layouts, you may want to select a landscape orientation or adjust the scale percentage in order to show
more of the columnar data.
You may want to define an Archive Window layout specifically for
archive reports.
After selecting your page setup options, select OK.
2. From the File menu select Print Archive Report.
VISE X User’s Guide
Section 2 Building an Installer
12–2
Archive Reports
3. In the Archive Report selection dialog you are presented with options for Report to
Print, Report Kind and Packages to include. From the Report to Print popmenu,
select the desired report.
Illustration 12-1: Archive Report selection
4. From the Report Kind popmenu select the output option desired for the report.
Illustration 12-2: Archive Report output options
5. If the Packages popmenu is enabled you may limit the report to cover only chosen
packages.
6. Click the Print... button to generate the archive report.
Chapter 12 Generating Archive Reports
VISE X User’s Guide
Generating Archive Reports
12–3
7. If To Text File was chosen, you are then asked for the saved report’s name and
location.
Illustration 12-3: Save Report As dialog
If To Printer is selected, the standard Print dialog follows.
Generating Archive
Reports
The following kinds of reports are available:
Report Type
Description
Packages
Provides a report of files to be installed organized by package.
You can select the packages for which you wish to view a report
from the Package popmenu. If you select a package or packages
from the popmenu, the report will only display information for
those packages; if you don’t specify any packages, the report will
contain information about all the packages in the archive.
Files
Provides a report of files to be installed organized by file.
Install Locations
Provides a report of install locations for each file in the archive,
including replace option, gestalt selector calls, information on
an Install If setting, information on an Execute If setting, and (if
uncompressed) disk assignment.
Diagnostic
Provides a report containing troubleshooting information, such
as files which are not associated with packages; packages which
contain no files; invalid resource IDs; missing external codes; or
external codes which are included in the archive but have not
been called.
Specific Packages
Lets you generate a report listing the files that are assigned to
the exact combination of packages that you select. For example,
if you only select Easy Install, the report will list any files that
are assigned to the Easy Install package but are not part of any
other package. If you select two packages, then the report will
list only the files that are assigned to both packages; items that
appear in one package but not the other will not be included in
the report.
Table 12-1: Archive Report Types
VISE X User’s Guide
Section 2 Building an Installer
12–4
Report Output
Options
Report Output Options
VISE X reports can be directed to a printer, to a text file or to the screen.
Report Type
Description
To Printer
Output is directed to the printer selected in the Chooser.
To Text File
Output is directed to a tab delimited text file created at the
location selected.
To Screen
Output is directed to an on-screen report.
Table 12-2: Archive Report Output Options
Chapter 12 Generating Archive Reports
VISE X User’s Guide
13–1
Chapter 13
Finding Items in an Archive
Find Feature
To find an item within an archive:
1. From the Edit menu select Find…
2. The Find dialog appears.
Illustration 13-1: Find dialog
VISE X User’s Guide
Section 2 Building an Installer
13–2
Find Feature
3. Select the archive item category upon which to search or choose Any Item to
search without restricting the search by category.
Illustration 13-2: Find by Archive Item Category
4. Select the archive item property upon which to search. For this example we chose
Created Date.
Illustration 13-3: Find Files by Created Date
Chapter 13 Finding Items in an Archive
VISE X User’s Guide
Find Feature
13–3
5. Select the operator to use for narrowing the search. For this example we chose to
limit our search to all files with a created date that is within 1 week of 10/15/2003.
Illustration 13-4: Selecting the Search Operator
6. The Find operation will start searching from the top of the archive and will search
down, including within folders, until it finds a file with properties which fall within
the search criteria. The found item will be selected and if it is within a folder it will
be revealed in the archive window item list. To find the next item with properties
which fall within the search criteria select Find Next from the Edit menu or use
the keyboard equivalent Command-G.
To Find Previous:
■
Hold down the Shift key while clicking the Find button; or
■
Use the keyboard equivalent Command-Shift-G; or
■
Hold down the Shift key and select Find Previous from the Edit menu.
7. If you check Select All Found in the Find window, all items within the archive
with properties which fall within the search criteria will be revealed and selected in
the archive window item list.
8. With all found items selected, changes can be made to the selected files at once by
holding down the option key and clicking the Get Info button. The resulting compound Get Info window allows you to apply settings changes to all selected items.
It is sometimes useful to see all items of a particular type in an
archive. For instance, find all alias action items. To do so, select the
desired type, select containing and make sure the field to search is
blank.
VISE X User’s Guide
Section 2 Building an Installer
13–4
Chapter 13 Finding Items in an Archive
Find Feature
VISE X User’s Guide
14–1
Chapter 14
Building the Final Installer
Before the Final
Build
Before building the final installer, make sure that everything in your archive is correct,
including:
■
Assignment of files to packages
■
Addition of external codes
■
Use of gestalt calls
■
General settings for the installer
It is recommended that you verify the archive and that you run a diagnostic archive report
to make sure that there are no problems in the setup of the installer.
Build Targets
All VISE X builds are controlled by Build Targets. Even if you choose not to use the Project Window or to set up your own Build Targets, each time the Build command is issued
the build is performed according to the settings of the active build target.
A build can be initiated by:
■
Selecting Build Installer… from the File menu.
■
Typing Command-B from the keyboard; or
■
Running an AppleScript that tells VISE X to Build.
All new archives have one build target which is the active build target. The active build target is indicated by a bullet next to the build target icon in the Project Window. While the
VISE X User’s Guide
Section 2 Building an Installer
14–2
Build Targets
active target is the target currently being edited, any number of targets can be checked in
the project window. When a build command is issued, all checked targets will be built.
Illustration 14-1: Active Default build target
For a new archive, the active build target is named Default Target and it has as its Format,
Application Bundle.
Illustration 14-2: Default Build Target
Setting up multiple Build Targets can enable you to produce an installer in multiple forms
and/or multiple locations. By setting up and then checking several build targets you can
automate the entire process of building multiple installers to multiple locations.
By setting up Build Targets you can preset:
■
Where the installer will be built
■
What type of installer, or Target, to build
Chapter 14 Building the Final Installer
VISE X User’s Guide
Building a Debug Installer
14–3
■
Whether to build the installer as a debug installer
■
Whether to create a Tarball (.tar.gz) version of the built installer segment
By setting up Disk Names you can preset:
■
What the installer segment(s) will be named
■
What the disk names should be
■
How big segment sizes should be
Below we will set up a build target for creating a debug installer.
Building a Debug
Installer
As in software development, the feedback available from a debug build can be valuable in
pinpointing faulty implementation. It is recommended that you build a debug installer
and run it through all options of Easy and Custom Install before building and releasing
your final installer.
A debug installer is identical to a non-debug installer in content and logic but contains an
additional window, the debug window. When using a debug installer, information is written to the debug window as each archive item is processed. Some of the information available in the debug window includes: gestalt checks, variable setting and testing, action item
results, and install if conditions.
Debug installers can be very helpful in tracking down install problems, verifying install if
conditions, and tracking the progress of Find actions or the Search Criteria within other
action items.
When a debug installer is run, a debug window is displayed to the left and behind the
Install window. As the install progresses, item execution information is written to the
Debug Window as shown below.
Illustration 14-3: Debug Installer with debug window
VISE X User’s Guide
Section 2 Building an Installer
14–4
Building a Debug Installer
To build a debug installer:
1. From the Archive menu select Show Project Window.
2. Select the Targets heading in the Project window and click the Add button.
Illustration 14-4: Adding a build target to the Project Window
3. Name the build target, select a Format type, and check the Create Debug checkbox. If you wish the build path to be other than where the VCT is located you can
edit the path by clicking on the Edit Path button. Click OK when you are done
setting up the build target.
Illustration 14-5: Creating a Debug build target
4. In the Project Window click just to the left of the Debug Target icon to make it the
active target. A bullet will appear next to the Debug Build build target indicating
Chapter 14 Building the Final Installer
VISE X User’s Guide
Building the Release Installer
14–5
that it is the active build target. Check the Debug Target and uncheck the Default
Target.
Illustration 14-6: Setting the Active Build Target
5. Select Build Installer… from the File menu.
Building the Release
Installer
To create the release installer:
1. Create a build target for your release installer:
■
Name the build target.
■
Choose a Format.
Target Format
Explanation
Disk Images
At build, installer disk images based on data from the
Disk Names List are created at the location designated
by the path field. Disk Names are used for disk image
names and Segments are saved within the appropriate
disk image volumes.
Folders/CD Segments
At build, an installer based on data from the Disk
Names List is created at the location designated by the
path field. Disk Names are used for folder names and
Segments are saved within the appropriate disk folder.
CD Installer
(Uncompressed)
At build, a CD installer is created at the location
designated by the path field and files are extracted from
the archive and copied to the same location as the CD
installer.
Table 14-1: Build Format Options
VISE X User’s Guide
Section 2 Building an Installer
14–6
Building the Release Installer
Target Format
Explanation
Application Bundle
At build, a single file application bundle installer
containing compressed archive items is created at the
location designated by the path field. This is the
preferred way to deliver a multi-language installer on
Mac OS X. It allows the proper display of single-byte
and double-byte character sets from within the same
installer.
Web Installer
At build, a web installer and designated group files are
created at the location designated by the path field. If
Upload Cab file(s) to Web Server at Build Time
(FTP sites only) is checked in the Web tab of Installer
Settings, the group file(s) are uploaded to the web
server designated in Download Sites from the Internet
menu.
Web Installer (w/Data)
At build, a web installer (containing all data as if user
had just downloaded it) and designated group files are
created at the location designated by the path field. If
Upload Cab file(s) to Web Server at Build Time
(FTP sites only) is checked in the Web tab of Installer
Settings, the group file(s) are uploaded to the web
server designated in Download Sites from the Internet
menu.
Table 14-1: Build Format Options
■
Make sure the Create Debug checkbox is NOT checked.
■
Set the path for the built installer. The default path for built installers is the
directory of the VCT.
■
Make post processing choices.
■
Close the build target and make it the active build target.
2. From the File menu, select Build Installer....
3. If your copy of VISE X is not registered, you will be asked to register the copy at
this time.
Illustration 14-7: VISE X Registration
If you select Later and build an installer with an unregistered copy of VISE X, the
installer will:
■
Chapter 14 Building the Final Installer
Display the VISE X splash screen to the customer before your splash screen,
alerting them that you used unlicensed software; and
VISE X User’s Guide
Building the Release Installer
14–7
■
Expire three days from the date that the unlicensed installer was built.
If your copy of VISE X is registered, then the VISE X splash screen will never be visible to the customer, and installer will not automatically expire.
VISE X User’s Guide
Section 2 Building an Installer
14–8
Chapter 14 Building the Final Installer
Building the Release Installer
VISE X User’s Guide
15–1
Chapter 15
Creating CD Installers
Creating a CD
Installer
This chapter explains how to create CD installers as single segments.
If you need to break your installers into separate segments for distribution on multiple CDs, you can use the “Folders/CD Segments”
Format option in the Build Target. For more information on Build
Target Format options, see “Build Targets” on page 21-9.
To create a CD Installer:
The Catalog Only
Question
1. Decide whether you want users to have direct access to the files on your CD.
By default the installer contains all of the files in a compressed format. Since the
files are stored inside of the installer they cannot be accessed directly. The customer
must run the installer to install your files.
If you do not want users to have direct access to the files on your CD you do not
need to perform any of the following steps. This guarantees that your customers
must go through the installer to install your files.
If you do want users to have direct access to the files on your CD, the installer can
also be set up to install normal Finder-draggable files. This is common on many
software CDs. Your customers can copy individual files to their hard drive and
bypass the installer if they wish. This can be good or bad depending on how much
control you want to give your customers.
VISE X User’s Guide
Section 2 Building an Installer
15–2
Creating a CD Installer
2. If you do want users to have direct access to the files on your CD select Installer
Settings from the Archive menu, go to the Advanced tab and check Only Store
Catalog Of Files.
Illustration 15-1: Installer Settings, Advanced Tab, Only Store Catalog Of
Files
Only Store Catalog Of Files is an often-misunderstood Advanced Setting option
that allows you to store only a catalog of your files in an archive, not the actual
compressed file data. Many people believe that you need to turn this option on to
build CD installers that can install uncompressed files. Not so! This option only
affects only how your files are stored in your archive file, NOT the installers you
build with it. It was implemented for developers with very large archives building
only CD installers in order to eliminate the time needed to compress files when the
archive is saved and decompress files while building the installer.
There are limitations for Catalog Only archives.
1) Only CD installers can be built from the archive.
2) The file hierarchy in the archive MUST match the file hierarchy
of the actual files on CD.
3)This option cannot be turned off once it has been turned on.
Chapter 15 Creating CD Installers
VISE X User’s Guide
Creating a CD Installer
15–3
When the Only Store Catalog Of Files option is turned on the following warning
will be displayed:
Illustration 15-2: Catalog Only Warning
Create a CD Installer
Build Destination
3. From the Archive menu select Show Project Window.
The Project Window is where Build Targets are created and activated. Build Targets
enable easy creation of multiple types of installers.
4. Select Targets in the Project Window and click the Add button to create a new
Build Target.
Illustration 15-3: Adding a new Build Target
VISE X User’s Guide
Section 2 Building an Installer
15–4
Creating a CD Installer
5. Name the new Build Target and set the Format popmenu to CD Installer.
Illustration 15-4: Creating a CD Installer Build Target
See Chapter 21-Advanced Project Management, for information on other Build
Target formats.
6. The Path defaults to {Vct folder}: meaning that the installer will be built to the
same location as the archive (VCT). Set the path to the location of your CD master
volume. When the installer is built, the files and the installer will be placed at the
location specified in the Build Target Path.
7. Select the OK button in the Build Target window.
Check the CD Target and make it the active target (represented by a bullet) by
clicking to the left of the CD Target icon.
Illustration 15-5: Activating a Build Target
Whenever the Build command is issued the checked Build Targets will be built.
Chapter 15 Creating CD Installers
VISE X User’s Guide
Creating a CD Installer
15–5
Set Installer Name
8. When built, the installer will be named based on the Installer Name field in its
Build Target. In the Installer Name field, type the name you wish to assign to the
installer and Click OK.
Building the CD Installer
9. Build the Installer. There are a number of ways to initiate a build:
Maintaining Finder Icon
Positions
■
By selecting Build Installer from the File menu.
■
By typing Command-B; or
■
By telling VISE X to Build from an AppleScript (see “Building an Install Set”
on page 24-8).
10. When building a CD installer, files are extracted from the archive and copied to
the same location as the installer. VISE X will honor .DS_Store file settings (thereby
maintaining icon positions) if that hidden file is present in a folder you add to your
archive. You can view .DS_Store files if present by opening the folder in the main
archive window. For more information, see “About Archives” on page 3-1.
Disk space is not checked when a CD-ROM installer is created, so
make sure that you don’t exceed the capacity of your storage media.
File Compression
Options for CD-ROM
Installations
By default, all items in the archive will be placed uncompressed on the CD. However, by
changing file and folder options at the archive window or the VISE X Get Info window,
you may specify that you only want individual items to be uncompressed on the CD.
Catalog Only On:
■
Files are copied from the source on the hard drive to the Build Target. All files
will be in a Finder draggable form.
Catalog Only Off:
■
If the Build Target is a CD installer, all files will be decompressed from the compressed data in the archive, to the Build Target.
■
If you have certain files/folders set to be on disk then those files/folders will be
decompressed to the Build Target while the remaining files will be compressed in
the installer.
For instructions on assigning specific items to be uncompressed on a CD, see “Storing the
Item Uncompressed in a Disk Image or Folder” on page 9-17.
VISE X User’s Guide
Section 2 Building an Installer
15–6
Chapter 15 Creating CD Installers
Creating a CD Installer
VISE X User’s Guide
16–1
Chapter 16
Maintaining Archives
Bringing the Archive
Up To Date
Bring Up To Date synchronizes your archive with the original source files, allowing you to
add, delete or modify the files in the archive without redefining packages or file information for a file. During the Bring Up To Date process, you will be given an opportunity to
verify differences and to decide if you would like new files to be added, obsolete files to be
deleted and similar files to be updated.
During VCT construction, if you have changed folder names in the
VCT or on the HD source without changing the folder name in the
other location (VCT or HD), it is necessary to perform a Validate
Paths operation before doing a Bring up To Date. The Validate Paths
operation is more comprehensive in its efforts to determine paths for
items. For more information on validating paths see “Validating
Paths” on page 16-4.
To bring an archive up to date:
1. Make sure that the source folder for the archive contains the new or modified files,
and that it’s closed so that the Finder has updated any new icon locations.
The best way to ensure that the Finder updates a folder’s .DS_Store
file (containing icon position information) is to log out and then
back in to Mac OS X. For more information, see “About Archives”
on page 3-1.
2. From the Archive menu in VISE X, select Bring Up To Date...
VISE X User’s Guide
Section 2 Building an Installer
16–2
Bringing the Archive Up To Date
3. If a folder can no longer be found at its old location, you will be asked to locate
the folder.
Illustration 16-1: Locate Folder Not Found at Old Location
4. If the folder is no longer valid, click Cancel. The folder will be marked as
<missing> in the Bring Up To Date window and will be deleted unless you
uncheck it.
When you need to permanently rename an item, you should do so at
the Finder, then by Bring Up To Date. Updating in this way will synchronize the archive items with the source items at the Finder.
If you rename an item within the archive only, Bring Up To Date will
cause the item to be renamed back to its old name.
Chapter 16 Maintaining Archives
VISE X User’s Guide
Bringing the Archive Up To Date
16–3
The Bring Up To Date window will then be displayed:
Illustration 16-2: Bring Up To Date window
5. Use the chart below to determine which items have been modified since the last
time you saved the archive.
Indicator
Meaning
The item has been selected for update.
At least one item within the folder has been selected for update.
<same>
The item has not changed
<different>
At least one item within the folder has changed
The item did not exist when the archive was created.
<new>
<newer>
The version of the item in the source folder is newer than the
item in the archive.
Table 16-1: Bring Up-To-Date Window Indicators
VISE X User’s Guide
Section 2 Building an Installer
16–4
Verifying an Archive
Indicator
Meaning
<FInfo changed>
Certain Finder information for the item, such as a locked or
unlocked state, has been changed.
(Finder icon positioning is contained in .DS_Store files when
present. See “About Archives” on page 3-1 for details.)
You do not need to select items whose Finder information has
changed. The information will be automatically updated when
you save the archive, though the file will not be recompressed.
If you do select an item whose Finder info has changed, the item
will be recompressed as well as include the new Finder
information.
<missing>
The item in the archive was not found in the source folder. That
item will be deleted from the archive if the checkbox for that
item remains selected.
Table 16-1: Bring Up-To-Date Window Indicators
6. To compare the old and the new versions of an item, select the item and click the
Get Info button. A box comparing the old file (on the left) and the new file (on
the right) will be displayed. Click OK to dismiss the comparison box.
7. Select any items that should be updated to the archive by clicking the checkbox on
the left of the item’s name. Items that have changed will automatically be selected
for updating.
8. By default, files that are added to an archive as a result of an update have the same
package assignment as its parent folder in the archive. To disable this feature, deselect Assign Parents Package to New Files at the top of the Update Archive window.
9. Click Update... to update the archive. If any files had the status of <missing>,
then a warning message will ask if you’re sure that you want to delete those files
from the archive.
Bring Up To Date and Embedded VCTs - The Don’t Update Packages on Imported VCT Files Archive Setting will affect what happens to embedded VCT items during Bring Up To Date. For more
information on this setting, see “Don’t Update Packages on
Imported VCT Files” on page 10-27.
Verifying an Archive
To verify that the files in an archive are intact, select Verify Archive from the Extras
menu. If you receive an error message, you should update the archive.
If you verify an archive for a CD installation which only contains a catalog of files to
install, you’ll be asked to locate the specific folders that resemble the archive. This ensures
that the hierarchy of files in the archive matches the files that will be used to create the
CD.
Validating Paths
To make sure that the paths for files in an archive are intact, select Validate Paths from
the Extras menu. If the paths from source to archive have changed, you will be asked to
locate new locations for source items.
Chapter 16 Maintaining Archives
VISE X User’s Guide
Validating Paths
16–5
During VCT construction, if you have changed folder names in the
VCT or on the HD source without changing the folder name in the
other location (VCT or HD) it is necessary to perform a Validate
Paths operation before doing a Bring up To Date. The Validate Paths
operation is more comprehensive in its efforts to determine paths for
items.
VISE X User’s Guide
Section 2 Building an Installer
16–6
Chapter 16 Maintaining Archives
Validating Paths
VISE X User’s Guide
Section 3
Building Updaters
17–1
Chapter 17
About VISE X Updaters
Why Use an
Updater?
Why Use VISE X
Updaters?
VISE X User’s Guide
Updaters are the best means to provide upgrades and quick fixes for your existing applications. Not only are they easy to create and distribute, they are an ideal way to let your customers know that you are constantly working to improve the product. Updaters are the
most convenient, cost-effective way to help your customers stay current because...
■
Updaters are small. Updaters only store information about the changes between
versions of an application—they are not complete releases of the application
itself. So, updaters are almost always small, and therefore easily distributed on
CD or via FTP and Web sites, commercial online services and bulletin boards.
■
Updaters are safe. VISE X updaters do not contain a new, complete version of
your software—they create a new application based on the differences between
the old and new versions. If a person does not have a copy of your original application, the updater will not create a new version. So, you can freely distribute
updaters without contributing to piracy of your products.
■
Updaters are fast. They are easy to create—just identify the source items (the items
you want to update) and the target items (the items you want to update to), customize your options, and click a button to build the updater. And, they are easy
for customers to use—you can even build updaters that automatically locate the
customer’s applications that are candidates for updating.
By combining an easy-to-use graphical interface with innovative development features,
VISE X is the ideal tool for creating updaters for any Mac OS X application. VISE X
updaters have...
■
A simple, flexible interface. Although you can precisely configure your updater
to meet your custom requirements, almost all development takes place in a single
window and one easy-to-understand dialog box. It’s simple to make changes and
test them immediately to make sure that you’ve designed the updater exactly the
way you want.
■
Support for multiple application versions. VISE X updaters do not limit you to
upgrading from only a single version number—you can build updaters that identify and upgrade multiple previous versions. So, if your customers might have
Section 3 Building Updaters
17–2
The Customer’s Perspective: A Sample Session
versions 1.1, 1.2, and 1.3 of your application, you can upgrade all of them to version 2.0 with a single updater.
The Customer’s
Perspective: A
Sample Session
■
“Double fail-safe” checksum security. VISE X updaters use checksums twice to
ensure the accuracy of an update: at the beginning of the update to make sure
that the selected item is a valid candidate for updating, and at the end of the
update to ensure that the newly updated application is 100% accurate and complete.
■
Powerful handling of resource exceptions. Your customer’s application is rarely
going to be exactly the same as when it shipped—resource information such as
registration, preferences, size and icons may have been changed. VISE X lets you
identify what resources are likely to have been modified by your customers and
choose whether to use the old resource or new resource in the updated application. For your convenience, VISE X updaters already list the most commonly
modified resources by default.
■
Security for the customer’s original item. VISE X updaters do not modify your
customer’s existing item—they generate an entirely new one. So, if an update is
canceled or unexpectedly interrupted, the customer’s original item will not be
modified or corrupted in any way.
■
Comprehensive localization features. VISE X supports the development of updaters in multiple languages from a single VISE X updater item. All you need to do
is include the VISE X updater item in your archive and follow the usual steps for
building a multi-language installer. VISE X automatically generates dialog boxes
and other application-generated messages in the languages you select.
■
Full integration with VISE X. You create VISE X updaters from within VISE X,
which gives you all the power and flexibility of VISE X installers in addition to
the updater technology. The combination of installer and updater capabilities
allows you to:
■
Update more than one file at a time
■
Install new files that aren’t part of the application’s original install set but
are associated with the upgrade (such as tutorials or samples)
The following is an example of the kind of session a customer might encounter when
using a simple updater created with VISE X.
Chapter 17 About VISE X Updaters
VISE X User’s Guide
The Customer’s Perspective: A Sample Session
17–3
The customer launches the updater, which displays an informative Read Me file that
explains what will happen as a result of the update. (The Read Me is optional.)
Illustration 17-1: Updater Read Me window
After the customer dismisses the Read Me file, the Select Destination window displays.
The customer selects the volume where MyApp 1.0 is located, and then clicks Continue.
Illustration 17-2: Updater Select Destination window
VISE X User’s Guide
Section 3 Building Updaters
17–4
The Customer’s Perspective: A Sample Session
The updater displays progress information.
Illustration 17-3: Updater Installing window
When the updater finishes, it informs the customer that the software was successfully
installed. The customer then clicks Quit.
Illustration 17-4: Updater Finish Up window
Chapter 17 About VISE X Updaters
VISE X User’s Guide
18–1
Chapter 18
Designing an Updater
This chapter contains some general guidelines for setting up an updater.
Basic Components
of an Updater
The basic components that you must identify when creating an updater
are:
■
All old versions of the item that may be on the customer’s system (the source
items)
■
The new version of the item (the target item)
■
What resources may have been modified in the original item (resource exceptions)
In a simple case, you might only need to identify a single source item to be updated and a
single target item to use as the new version. However, the situation can be more complicated, as discussed below.
Handling Multiple
Versions
VISE X updaters allow you to include multiple versions of a source item within a single
updater.
For example, if your product has a full release numbered 1.0 and an incremental release
numbered 1.1, and you’re creating the updater for a release numbered 1.2, you can identify
both the 1.0 version and the 1.1 version as source items. Then, customers who have either
1.0 or 1.1 can use your updater to upgrade their version to 1.2.
For other examples of using multiple versions of a source item, see “Designing Your
Updater” on page 18-2.
Handling User System or
Program Modifications to
Resources or the Data
Fork
VISE X updaters identify source items on the customer’s system by comparing them to the
source items that you included when you built the updater. If the resources of the customer’s item have been changed so that they no longer match the resources of the source
item in your updater, the updater will refuse to update it. However, the customer, the system, or a program may have modified the source item’s resources by a common action
such as entering registration information or attaching a custom icon.
To handle these resource exceptions, VISE X lets you identify the resources that may have
been modified, so that source items can be correctly updated. Additionally, you can
VISE X User’s Guide
Section 3 Building Updaters
18–2
Designing Your Updater
choose whether to override the modifications or to apply them to the newly installed
item. (For example, if the customer attached a custom icon to the application, you can
choose to use the custom icon on the updated version or to replace it with the icon of the
updated version.)
Because your application may store preferences or other information in the data fork,
VISE X also provides a means to copy or override information in the data fork of the
source item.
For detailed information on handling resource or data fork modifications to your source
items, see “Identifying Resource and Data Fork Exceptions” on page 19-6.
Designing Your
Updater
As with any type of installer project, it’s good practice to plan ahead before building your
updater. Use the following guidelines to help you develop an update scheme:
1. List all the possible versions of the source item that a customer may have installed
that you wish to update. An example source list might be:
■
MyApp 1.0.0
■
MyApp 1.0.1
■
MyApp 1.0.2
You’ll need to locate unmodified copies of each item to use as source items when
creating your updater.
2. List the target item, which is the item the updater should create when updating any
item from your source list. An example target list might be:
■
MyApp 1.0.3
You’ll need to use an unmodified copy of the target item when creating your
updater.
3. Determine if there are any resources in the customer’s source item that may have
been added, removed, or modified since the item was installed. Examples of these
types of resources are those the system modifies, such as SIZE and custom icon
resources, or resources that the program itself modifies such as registration or preference resources. (Because SIZE and custom icon resources may be modified by
any customer, they are included in the Resource Exception lists by default.)
Any resources that may have been modified must be included in one
of the three Resource Exception lists in the updater; otherwise, the
updater will see that they have been modified and not perform the
update. Information about how to enter resource information into
the Resource Exception lists can be found in Chapter 19-Building
Updaters.
4. Decide on other settings for the updater, such as the following:
■
What should the newly created target item on the customer’s system be
called after the update?
■
Should the original source item on the customer’s system be removed?
■
What creation and modification dates should be used for the newly created
target item on the customer’s system?
For detailed information about available settings for an updater, see “Modifying
Chapter 18 Designing an Updater
VISE X User’s Guide
Designing Your Updater
18–3
Updater Settings” on page 19-11.
5. List auxiliary requirements for the updater, such as items to be installed in addition
to the updated item(s). For more information, see “Setting Auxiliary Options” on
page 19-19.
VISE X User’s Guide
Section 3 Building Updaters
18–4
Chapter 18 Designing an Updater
Designing Your Updater
VISE X User’s Guide
19–1
Chapter 19
Building Updaters
This chapter contains detailed information about building updaters with VISE X. Before
you begin building an updater, be sure to see Chapter 18-Designing an Updater.
For the purposes of this documentation, “VISE X updater” refers to
a VISE X installer that incorporates updater functionality. You add
updater functionality by including at least one updater item in the
VISE X archive that you use to build the installer. More information
on updater items is available in this chapter.
How VISE X
Updaters Work
When you build an installer that contains updater items, VISE X updater code is included
in the installer. When an installer encounters an updater item in the install set, it does not
simply install the item as it would a normal file. Instead, it installs the updater item in a
temporary folder, updates the target item, and finally deletes the updater item. This process is invisible to your customer.
Single File versus
Application Bundle
The procedure for building an updater varies slightly depending on whether you need to
update:
■
A CFM executable that is deployed as a single-file application; or
■
An application bundle
Information on building an updater for a single-file application begins below. Also see
“Building an Updater for an Application Bundle” on page 19-19.
Building an Updater
For a Single-File
Application
VISE X User’s Guide
The following is the general procedure for building an updater for a single-file application.
The rest of this section will explore each item in detail.
1. Create your updater items, which involves the following steps:
■
Identify the source and target items for the updater item.
■
Modify the Resource Exception lists as needed.
Section 3 Building Updaters
19–2
Building an Updater For a Single-File Application
■
Select the settings for application name, modification and creation dates and
so on.
■
Build the updater item.
■
Test the updater item.
■
Save and close the updater item.
See “Creating an Updater Item” on page 19-2.
2. Make sure that each updater item can locate the item it will be updating. To do
this, you must either:
■
Assign the updater item to a Find action item to locate the item on the target system, or…
■
Name the updater item with the same name as the item you are updating.
See “Enabling Updater Items to Find Items to Update” on page 19-14.
3. Set the default update location for the user. In the Installer Settings Interface tab,
set the Default Install Location criteria to find a file within your product’s main
folder, or to find the folder itself. See “Setting the Default Install Location” on
page 19-15.
4. If you wish to use the Updater interface, select Updater from the Display Interface popmenu in the Installer Settings Interface tab. See “Setting Interface
Options” on page 19-15.
5. Set up any needed auxiliary options, such as items to be installed in addition to the
updated item(s). See “Setting Auxiliary Options” on page 19-19.
6. Build the updater.
Creating an Updater
Item
Before you start creating an updater item, be sure that you have the following:
■
Unmodified copies of all the source items and target items for the updater
■
If necessary, the resource types and ID numbers for resources that may have been
modified by the system, program or customer
To create an updater item:
1. At the Finder, launch the VISE X application.
2. If you have not registered your copy of VISE X, the registration window will be displayed. If you fail to register your copy of VISE X, the updater you create will display a splash screen letting your customers know that you used an unlicensed
development tool. Your unregistered updaters will also expire after three days.
3. From the File menu, select New Archive…. A standard file dialog box will be displayed.
4. Enter a name for the archive file.
5. Click Save. An Archive window will open, displaying the name that you entered for
the file.
6. From the Archive menu, select New Updater, and then Single File.
7. Enter a name for the new item and click Create.
Chapter 19 Building Updaters
VISE X User’s Guide
Building an Updater For a Single-File Application
19–3
8. Set up the updater item. An explanation of that process begins with “About the
Updater Window” on page 19-4 and ends with “Testing the Updater Item” on
page 19-14.
9. Close the updater window and save changes to the updater item if necessary.
Modifying an Existing
Updater Item
To modify an existing updater item:
1. Launch VISE X.
2. From the File menu, select Open Archive... A standard file dialog will be displayed.
3. Locate and select the VCT file containing your updater item.
4. Click Open.
5. In the VISE X archive window, select the updater item and click the Get Info button. The updater item’s Get Info window will be displayed.
Illustration 19-1: Updater item Get Info window
6. Click the Show Files button in the upper right corner of the Get Info window.
The updater window will be displayed.
7. Make any changes necessary to the updater item.
8. Compare the Source and Target items if necessary.
9. Close the updater window and save changes to the updater item.
VISE X User’s Guide
Section 3 Building Updaters
19–4
About the Updater
Window
Building an Updater For a Single-File Application
All actions for creating updater items will be performed in the Updater window, which
appears below:
Illustration 19-2: Updater window
The following is a brief description of each item in the window:
■
The Source Items field is where you’ll identify the source (original) items that
are eligible for updating. This field can contain up to eight different source items.
It can display four source items at a time, and will grow as needed.
■
The Target Item field is where you’ll identify the target (new) item, which is the
item the updater should create when updating any item listed in the Source
Items field.
■
The Resource Exceptions item displays the fields where you will identify which
resources may have been modified by the program, system or customer, and
what action should be taken by the updater in that case.
■
The Trash Can allows you to remove items from the source and target item lists
by dragging them over the icon.
■
The Add Item... button lets you add an item to the currently selected field. You
can also add items by drag and drop directly from the Finder.
■
The Settings... button displays the Updater Settings window, where you can
make several choices regarding the actions of the updater item.
■
The Show Info button displays an Updater Item Info window.
■
The Test… button becomes active after you’ve built an updater item through the
Compare feature. It allows you to test the actions of the updater without quitting
VISE X.
The delete and name options that you have set are overridden for the test to prevent you from accidentally modifying one of the items that you used to build the
updater item.
■
Chapter 19 Building Updaters
The Compare button becomes active after you have added at least one source
item and one target item. It builds an updater item for the items and options
that you identified.
VISE X User’s Guide
Building an Updater For a Single-File Application
Adding Items
19–5
Each updater item must identify at least one source (original) item and one target (new)
item.
Drag and drop is the easiest way to add items to the updater item
Source Items and Target Item fields, instead of using the Add Item…
dialog. You can also drag and drop items between fields within the
updater window.
Adding Source Items to
the Updater Item
To add a source item, perform one of these two procedures:
■
Drag the icon for the item from the Finder into the Source Files field in the
Updater window.
OR
1. Select the Source Items field in the Updater window and then do one of the following:
■
Click Add Item...
■
Double-click the field.
A dialog box will be displayed.
2. Locate and select the desired item.
3. Click Add. The name of the added item will be displayed in the Source Items field.
4. Repeat as needed until all source items are identified. You can identify up to eight
items. The Source Items field will grow as needed to display all the items that you
identify.
Adding Target Items to
the Updater Item
The Target Item field can contain only one item. Adding an item to the Target Item field
will replace any item that is already listed there.
To add a target item, perform one of these two procedures:
■
Drag the icon for the item from the Finder into the Target Item field in the
Updater window.
OR
1. Select the Target Item field in the Updater window and then do one of the following:
■
Click Add Item...
■
Double-click the field.
A dialog box will be displayed.
2. Locate and select the desired item.
3. Click Add. The name of the added item will be displayed in the Target Item field.
Removing Items from
the Updater Item
VISE X User’s Guide
If you wish to remove a source or target item from the updater item, select the item and
drag it over the Trash Can icon at the lower left of the window. When you release the
mouse, the item will automatically be removed.
Section 3 Building Updaters
19–6
The Updater Item
Information Window
Building an Updater For a Single-File Application
The Updater Item Info window displays important information about the items included
in your updater item, such as format, size, version and location.
Illustration 19-3: Updater Item Info
The Item Information window always remembers its position on the screen, so you can
move it to a convenient location and it will always appear there.
To show the Item Information window:
1. Select the Show Info button from the updater window.
2. Click once on an item in the updater window to update the information.
To hide the Item Information window:
■
From the File menu, select the Close command.
OR
■
Identifying Resource
and Data Fork
Exceptions
Click on the close icon of the Updater Item Info window.
VISE X updaters identify files on the customer’s system by comparing them to the source
items that you included in the updater. If a resource in the customer’s source item has
been modified by the system, program or customer, the updater will not update the item
unless that resource has been flagged as an acceptable modification.
You can identify the resources that may have been changed, added, or removed in the customer’s source item. This allows an updater to update source items even if the identified
resources don’t match. You can also choose whether you want the updater to ignore the
modified resources or copy them into the new item.
Chapter 19 Building Updaters
VISE X User’s Guide
Building an Updater For a Single-File Application
19–7
The following is a picture of the Resource Exception lists, containing VISE X’s default
resource exceptions. You should only add resources to these lists that may have been modified, added, or deleted in the customer’s source item.
Illustration 19-4: Updater window showing default Resource Exceptions
Resources are identified by their four-character name and range of associated ID numbers.
(For example, in the Keep Old If Exists field, both SIZE 0 and SIZE 1 are identified for
use because the range 0 to 1 is identified.) If only one ID number is appropriate for the
resource, the same number should be used in the starting and ending columns within the
field. (For example, in the Keep Old If Exists field, only icl4 -16455 is identified for
update, since the items in the starting and ending number columns are the same.)
The meaning of each field is described in the table below
Always Use
New
Always Keep
old
Keep Old if
Exists
If resource in this
field is
encountered…
Always replace
with the resource
of the target item
Always use the
resource of the
customer’s own
source item
If the customer has
modified or added
this resource, use
their changes
Example
If you want the
newly installed
item to have the
same SIZE -1
resource as the
target item you
placed in the
updater, instead of
the SIZE -1
resource in the
customer’s source
item.
If you have a
registration
resource in your
application, you
can transfer the
registration
information to the
newly updated
item.
If the customer has
added a custom
icon to the source
item or modified
its minimum and
preferred memory
sizes in the Get
Info window, the
changes will be
carried over to the
newly updated
item.
Table 19-1: Resource Exception categories
VISE X User’s Guide
Section 3 Building Updaters
19–8
Building an Updater For a Single-File Application
VISE X includes the following defaults for the common customer actions of modifying
the memory requirements or adding a custom icon in the Finder’s Get Info window:
Resource
String ID
Ending ID
Resource Exception?
SIZE
-1
-1
Always Use New
SIZE
icl4
icl8
ICN#
ics#
ics4
ics8
MPSR
0
-16455
-16455
-16455
-16455
-16455
-16455
0
1
-16455
-16455
-16455
-16455
-16455
-16455
32000
Keep Old If Exists
Table 19-2: Default Resource Exceptions
You may modify or remove the default resources if necessary.
On Mac OS X, customers do not have the ability to modify an application’s memory requirements from the Finder’s Get Info window.
However, that option is available for Carbon applications running in
the Classic environment. The ability of customers to modify the
memory requirements of some applications is the reason that VISE X
includes SIZE as a default resource exception for updaters.
Example of Using
Resource Exception Lists
Chapter 19 Building Updaters
In the following example, there are several resources that may have been modified in the
customer’s original source item: the registration resource (regs 128), which we wish to copy
from the customer’s source item into the target item, and a preference resource (pref 128)
that we wish to ignore so that the target item’s pref resource is always used. Additionally,
we’ll leave the default resources for SIZE and custom icons in place.
VISE X User’s Guide
Building an Updater For a Single-File Application
19–9
The updater item for this situation will look something like this:
Illustration 19-5: Updater item Resource Exceptions
Data Fork Exceptions
for CFM Files
Normally, the data fork of a CFM application consists only of executable code, so the
data fork will never be modified. If your application uses the data fork in this way, you do
not have to worry about data fork exceptions, and you can skip to “Identifying Resources”
on page 19-10. Otherwise, if your application uses the data fork to store information other
than executable code, such as registration information or multiple code fragments, you
may need to identify the data fork as a resource exception. To do so, you should:
■
Use the resource type <df> to represent the data fork.
■
Read the information that follows to determine which starting and ending ID
numbers to use.
The <df> resource with appropriate starting and ending ID numbers can be placed in any
column in the Resource Exceptions lists as described earlier in this section.
The cfrg Resource
CFM applications contain a code fragment resource (cfrg), which indicates that the file
contains code, and identifies the location and size of each code fragment. (See Inside Macintosh: PowerPC System Software for a description of the Code Fragment Manager.)
The location and size of each code fragment in the data fork are identified by the values in
two fields of the cfrg resource: offset and length. (The resource contains other fields that
allow for code fragments that are not in the data fork; however, these are beyond the
scope of VISE’s data fork exceptions.)
Normally, there will only be a single code fragment whose offset is 0 (kZeroOffset) and
length is 0 (kWholeFork). This indicates that the code fragment occupies the entire data
fork.
If there is more than one code fragment, the offset field will identify the position in the
data fork where the code fragment begins. The length field identifies the length of the
code fragment, in bytes. For example, a code fragment with offset 32 and length 500
means that the code fragment begins at byte 32 of the data fork and continues for 500
VISE X User’s Guide
Section 3 Building Updaters
19–10
Building an Updater For a Single-File Application
bytes. VISE X also knows that a code fragment will always begin on a 16-byte boundary so
it will perform any necessary padding.
If Your cfrg Resource Has
Multiple Code
Fragments...
It’s possible that your cfrg resource will have more than one code fragment, signified by
two or more pairs of offset and length fields.
For example, you may have an optional code fragment that is only installed on certain
machines. In this case, the first offset and length of the cfrg resource will identify the locations of the main code fragment, and the second offset and length of the cfrg resource will
identify where the optional code fragment is stored. Since this second code fragment may
or may not exist in the customer’s source item, you must identify it as a resource exception. In this case, use <df> 2 to indicate the second code fragment, and enter it in the
Optional Copy Resource Exception list. The updater will then look at the second code
fragment’s offset and length, and if the data is present, either ignore it or copy it over to
the new target item (depending on which Resource Exception list you put it in.)
To identify a code fragment as a resource exception, the first pair of offset and length
identifiers will comprise <df> 1; the second pair of offset and length identifiers will comprise <df> 2; and so on. To enter this information into the Resource Exception lists of the
updater item, enter <df> x x in the appropriate column, where x signifies whether it’s the
first, second or third (etc.) pair of offset and length identifiers in the ‘cfrg’ resource.
VISE X only supports placing either the first or last code fragment in a Resource Exception list.
If Your cfrg Resource Has If your file’s data fork has only one code fragment occupying the entire data fork, you
Only One Code Fragment... probably won’t have to worry about data fork exceptions. The only circumstance under
which data fork exceptions can become relevant is if the program manually appends other
information, such as registration data, to the end of the data fork.
Identifying Resources
To enter resource exception information:
1. If the Resource Exception List fields are not displayed, click the triangle to the left
of the words Resource Exception Lists, or press Command-R.
2. If blank lines are visible in the field where you wish to enter a resource, click the
mouse in the field. A new line will be added to the field.
If the field contains more than four entries (as the Keep Old If Exists field does by
default), click the mouse in the field where you wish to add a resource and press
Tab to move through the entries until a new line is added to the field.
No matter how you create the new line, the area for the four-character resource
type will be selected so that you may immediately enter the information, and 0 will
be entered by default for both the starting and ending ID numbers.
3. Enter the four-character type of the resource you wish to identify.
4. Press Tab to move the mouse to the column for the starting ID number.
5. Enter the starting ID number of the resource.
6. Press Tab to move the mouse to the column for the ending ID number.
7. Enter the ending ID number of the resource.
8. To add another resource in the same column, press Tab to create a new line and follow steps #3-7, above.
To add a resource to another column, follow steps #2-7, above.
Chapter 19 Building Updaters
VISE X User’s Guide
Building an Updater For a Single-File Application
19–11
9. From the File menu, select Save to save your changes.
Modifying Resource
Information
To modify resource information that’s already entered:
1. Select the item you wish to modify. You may select a resource name or a starting or
ending number.
2. Modify the information as desired.
3. From the File menu, select Save to save your changes.
Deleting a Resource
To remove an entry for a resource:
1. Select the name of the resource you wish to remove.
2. Press the Delete key.
3. From the File menu, select Save to save your changes.
You do not need to delete the resource ID numbers. Because the name of the
resource has been removed, updaters that you build will not contain that resource’s
information.
Modifying Updater
Settings
Settings are modified in the Updater Settings window, displayed here:
Illustration 19-6: Updater Settings
The following items may be modified for updater items:
VISE X User’s Guide
■
Whether the customer’s original item is deleted after installing the updated version
■
What name is used for the newly installed item
■
What creation and modification dates are used for the newly installed item
Section 3 Building Updaters
19–12
Modifying File Options
Building an Updater For a Single-File Application
To modify file options for updater items:
1. Click the Settings... button to display the Updater Settings window.
2. Hold down the mouse over Delete Original and select one of the following items
from the popmenu:
■
If you do not want the original source item on the customer’s machine deleted,
select Do Not Delete Original After Update.
■
If you want the original source item on the customer’s machine to be deleted
after a successful update, select Delete Original After Update.
■
If you want the customer to decide whether or not the original source item on
the customer’s machine should be deleted, select Ask User For Delete Permission. When the updater is run, a dialog box will appear that asks the customer
whether the original should be deleted.
■
If you want the original source item on the customer’s machine to be moved to
the Trash, select Move Original to Trash (the default option).
3. Hold down the mouse over New File Name and select one of the following
options from the list:
■
To display a dialog box that asks the customer to enter a name for the new item,
select Ask User For Name. If selected, the Default Name field will appear below
the popmenu. If you enter a name in the Default Name field, the default name
will appear to the customer in the dialog box.
■
To name the newly updated item with the same name as the original source item
on the customer’s machine, select Same As User’s File Name.
■
To name the newly updated item with the same name as the target item that you
included in the updater application, select Same As Target File Name (the
default option).
■
To automatically name the newly updated item with the name of your choice,
select Use Default Name. If selected, the Default Name field will appear below
the popmenu. Be sure to enter a name in the Default Name field.
4. If you selected Use Default Name, or if you selected Ask User For Name and
wish for a default name of your choice to appear in the dialog box, enter the
desired name in the Default Name field.
If the new item is named the same as the original, and the original
item is not deleted, and both the new and original items are stored in
the same location, then the original will be renamed with “.old”
appended to the item’s name. For example, MyApp 1.0 would
become MyApp 1.0.old.
Chapter 19 Building Updaters
VISE X User’s Guide
Building an Updater For a Single-File Application
19–13
If an updater item’s delete option is left at its default, Move Original To Trash, and the installation is canceled, the original item will
be moved back out of the trash to its previous location and the new
item deleted. This allows a user’s volumes to be restored to their original state if a multi-item update fails.
Modifying Creation and
Modification Date
Options
To choose the desired creation and modification dates for the newly installed item, follow
these steps in the Date Options section of the Updater Settings window:
1. To choose the creation date for the item that will be installed, hold down the
mouse next to Set Creation and select the desired setting:
■
If you want the creation date of the newly installed item on the customer’s
machine to be the date that the customer runs the updater, select Date User
Runs Updater.
■
If you want the creation date of the newly installed item on the customer’s
machine to be the date that you built the updater, select Date the Updater is
Built.
■
If you want the creation date of the newly installed item on the customer’s
machine to be the same as the creation date of the original target item that you
included in the updater, select Creation Date of New Version (the default
option).
■
If you want the creation date of the newly installed item on the customer’s
machine to be the same as the creation date of the customer’s source item that
was replaced, select Creation Date of User’s File.
2. To choose the modification date for the item that will be installed, hold down the
mouse next to Set Modification and select the desired setting:
Building the Updater
Item
■
If you want the modification date of the newly installed item on the customer’s
machine to be the date that the customer runs the updater, select Date User
Runs Updater.
■
If you want the modification date of the newly installed item on the customer’s
machine to the be the date that you built the updater application, select Date
the Updater is Built.
■
If you want the modification date of the newly installed item on the customer’s
machine to be the same as the modification date of the target item you included
in the updater application, select Modification Date of New Version (the
default option).
■
If you want the modification date of the newly installed item on the customer’s
machine to be the same as the modification date of the source item that was
updated on the customer’s system, select Modification Date of User’s File.
When you have identified the source and target items, created your Resource Exception
lists, and chosen your updater settings, the next step is to build the updater item. When
you build the updater item, VISE X compares the source items and target items that you
identified and analyzes the differences.
To build your updater item:
1. Make sure that you’ve set up the updater item as desired.
VISE X User’s Guide
Section 3 Building Updaters
19–14
Building an Updater For a Single-File Application
2. Click Compare. The Comparing Files... window will appear, displaying a progress
gauge. When the Comparing Files... window disappears, the build is complete.
Once you have built the updater item, you may test its functions.
Testing the Updater
Item
VISE X’s built-in Test feature lets you make sure that you have built the updater item as
desired without having to build a separate updater. This allows you to identify desired
changes quickly, without having to regenerate a new updater each time.
The Test Update feature does not display the same user interface features as the updater.
Instead, it simply lets you select an item to update; performs the update; and creates a new
version of the target item on your system, which you must name.
The Test Update feature will update your items exactly as an updater would, with the following exception: to prevent you from accidentally modifying or deleting one of the items
used to build the updater, any naming and deletion options that you set in the Updater
Settings section will be overridden. The updater will act as if the “Do Not Delete Original” and “Ask User For Name” options have been selected—you will always be asked how
you wish to name the items, and the original will never be deleted.
To test the updater item:
1. Make sure that you have built the updater item.
2. Click Test.
The application will guide you through the item selection and updating process.
If the updater item behaves as desired, you can close the updater window to include the
updater item in an archive. If the updater item does not behave as desired or expected,
modify it as needed per the instructions in the preceding parts of this chapter.
Enabling Updater Items Once you create an updater item, you need to make sure it can find the items on the tarto Find Items to Update get system that should be updated. There are two ways to do this, depending on where the
item to be updated is located and whether it may have been renamed or not:
1. If the item to be updated may have been renamed, or is not in the current install
location...
If the file or application may have been renamed or the current install location is
not correctly set to the folder containing the item you are updating, you must create a Find action item to locate the correct item. For example, this would be necessary if a customer may have renamed your application, or if you need to update a
file in a folder other than the folder containing the main application.
■
Create a Find action item to locate the item you wish to update on the target system. Make sure you set the Find Action's Stop Install If Find Fails
option if you wish the installation to be canceled if the item to update cannot be found.
■
Select the updater item, and use the Install To: popmenu to set the installation location as the result of the Find action you created.
■
Make sure that the Find action item appears before the updater item it’s
attached to in the archive window.
2. If the item to be updated will not have been renamed, and the current install location is correct...
Some items will not typically be renamed by the customer. For example, many
applications have tools or plug-in files that it looks for by name in a certain loca-
Chapter 19 Building Updaters
VISE X User’s Guide
Building an Updater For a Single-File Application
19–15
tion. If you are certain that you are updating an item that will not have been
renamed and the install location is correctly set to the folder containing the item
you are updating, follow these steps:
Setting the Default
Install Location
■
In the archive, rename the updater item to the same name as the item you
wish to update on the target system. For example, if you want to update a
file that’s definitely called MyApp Dictionary on the target system, and your
updater item is called Update to <MyApp Dictionary>, rename the
updater item in the archive to MyApp Dictionary.
■
Select the updater item, and use the Install To: popmenu to identify the
location of the file to update on the target system.
Set a Default Install Location so that the updater will default to the folder containing the
items that the user needs to update.
To set the Default Install Location for an installer containing updaters:
1. From the Archive menu, select Installer Settings…
2. In the Installer Settings Interface tab, click the Set Default Install Location button.
3. Click Set Default Install Location... and create a Find action item to locate the
item on the target system you wish to update.
Illustration 19-7: Sample Default Install Location
When the customer runs the installer, the default installation location will execute
the Find Action and default the install to the correct location.
Setting Interface
Options
VISE X User’s Guide
VISE X lets you choose to present a slightly different interface to the customer for installers that contain updater items. The basic differences between an Updater interface and a
regular installer interface are the following:
Section 3 Building Updaters
19–16
Building an Updater For a Single-File Application
■
When installing and updating items, the Updater interface displays “Updating” as the progress description. The regular installer interface displays
“Installing” in that situation.
■
For the Select Destination window, the Updater interface displays only the
volume that meets the Install Location criteria you specified. The regular
installer interface displays all available volumes in that situation.
You must have a Default Install Location set before selecting the
updater interface.
To use the Updater interface feature:
1. From the Archive menu, select Installer Settings. The Installer Setting Interface
tab will be displayed.
2. From the Interface popmenu, select Updater.
Illustration 19-8: Setting the Updater Interface
3. When you are finished, click OK.
4. To build the installer, click the File menu and select Build Installer…
Updater Interface
When you choose to display an “Updater” interface, the built installer will be similar to
the following example.
For the opening window, the updater displays an informative Read Me file that explains
what will happen as a result of the update. (The Read Me is optional.) At this point, the
Chapter 19 Building Updaters
VISE X User’s Guide
Building an Updater For a Single-File Application
19–17
only visible difference between the Updater interface and the regular installer interface is
the dimmed progress bullet that reads “Updating” rather than “Installing.”
Illustration 19-9: Installer with Updater Interface
After the customer clicks Continue, the updater displays the Select Destination window.
Here the updater displays only the volume that meets the Install Location criteria you
specified. The regular installer interface displays all available volumes in this case.
Illustration 19-10: Updater Select Destination window
VISE X User’s Guide
Section 3 Building Updaters
19–18
Building an Updater For a Single-File Application
When installing and updating items, the Updater interface displays “Updating” as the
progress description. The regular installer interface displays “Installing” in this case.
Illustration 19-11: Updater Updating window
For the window displayed at the end of the update, the only visible difference between the
Updater interface and the regular installer interface is the dimmed progress bullet that
reads “Updating” rather than “Installing.”
Illustration 19-12: Updater Finish Up window
Chapter 19 Building Updaters
VISE X User’s Guide
Building an Updater for an Application Bundle
19–19
If you do not choose the Updater interface, the only visible difference to the customer
between an installer containing updater items and a regular installer is in the progress
gauge. During installation, two bars will be visible (as illustrated below): one for the progress of the general install, and one for the progress of the updates.
Illustration 19-13: Updater dual progress dialog
This type of progress will be displayed whether you choose the Updater interface option
or not.
Setting Auxiliary
Options
Once you've set up your updater to update items, the final step before building the
updater is to set up any auxiliary options. These options can include anything outside of
the standard updater functionality, such as the following examples:
■
Using a custom background image—see “Adding a Background Image” on
page 10-17
■
Suppressing the main updater window (the Installation Type window, which
shows Easy Install and Custom Install options)—see “Choosing Interface Items to
Suppress” on page 10-5
■
Displaying Read Me and License Agreement files—see “Adding Read Me and
License Agreements to the Installer” on page 10-11
■
Installing items in addition to the updated items—see “Adding Files to the
Archive” on page 3-3
■
Adding aliases to the Mac OS X Dock, or to the StartupItems folder—see “Dock/
Startup Items Options” on page 5-43
For the updater examples in this user guide (“The Customer’s Perspective: A Sample Session” on page 17-2, “Updater Interface” on page 19-16 and “Updater Interface” on
page 19-32), we used a Read Me file to instruct the customer on how to select items for
updating. Also, we suppressed the main updater window because there was no need for the
customer to select installation type.
Building an Updater
for an Application
Bundle
The following is the general procedure for building an updater for an application bundle.
The rest of this section will explore each item in detail.
1. Create a bundle updater, which involves the following steps:
■
Name the bundle updater with the same name as the bundle to be updated.
■
Identify the source and target items for the bundle updater.
■
Build the bundle updater.
■
Save and close the bundle updater.
See “Creating a Bundle Updater” on page 19-20.
2. Make sure that your bundle updater can locate the item(s) it will be updating. To
do this, you must assign the bundle updater to a Find action item to locate the
VISE X User’s Guide
Section 3 Building Updaters
19–20
Building an Updater for an Application Bundle
item(s) on the target system. See “Enabling Bundle Updaters to Find Items to
Update” on page 19-24.
3. For each updater item within your bundle updater, do the following as needed:
■
Modify the Resource Exception lists.
■
Modify the default settings for file name, modification and creation dates
and so on.
See “Modifying an Existing Updater Item” on page 19-26.
4. If you identified more than one source item for your bundle updater, you will need
to construct your updater logic to search the target system for all versions that are
eligible for updating. See “Accounting for Multiple Source Items” on page 19-28.
5. Set the default update location for the user. In the Installer Settings Interface tab,
set the Default Install Location criteria to find a version of your product that is
eligible for updating. See “Setting the Default Install Location” on page 19-30.
6. If you wish to use the Updater interface, select Updater from the Display Interface popmenu in the Installer Settings Interface tab. See “Setting Interface
Options” on page 19-31.
7. Set up any needed auxiliary options, such as items to be installed in addition to the
updated item(s). See “Setting Auxiliary Options” on page 19-35.
8. Build the updater.
Creating a Bundle
Updater
Before you start creating a bundle updater, be sure that you have unmodified copies of all
the source items and target items for the updater. Also, make sure that the items all have
the same name. Having identical names for all the source and target items is a requirement
for building a functional bundle updater.
By default, your bundle updater will update .DS_Store files as needed
to make icon positioning on the target system match that of your
target item. If you do not need to maintain icon positions, you can
set up your updater to ignore .DS_Store files. The setting is available
in the Installer Settings/Advanced tab.
To create a bundle updater:
1. At the Finder, launch the VISE X application.
2. If you have not registered your copy of VISE X, the registration window will be displayed. If you fail to register your copy of VISE X, the updater you create will display a splash screen letting your customers know that you used an unlicensed
development tool. Your unregistered updaters will also expire after three days.
3. From the File menu, select New Archive…. A standard file dialog box will be displayed.
4. Enter a name for the archive file.
5. Click Save. An Archive window will open, displaying the name that you entered for
the file.
6. From the Archive menu, select New Updater, and then Bundle.
Chapter 19 Building Updaters
VISE X User’s Guide
Building an Updater for an Application Bundle
19–21
7. Enter a name for the new bundle updater. The name must exactly match that of
the bundle to be updated. For example, if the bundle updater will update
MyApp.app, enter MyApp.app. When you have entered the name, click Create.
8. Set up the bundle updater. An explanation of that process begins with “About the
Updater Window” on page 19-22 and ends with “Building the Bundle Updater” on
page 19-24.
9. Close the updater window and save changes to the bundle updater if necessary.
Modifying an Existing
Bundle Updater
To modify an existing bundle updater:
1. Launch VISE X.
2. From the File menu, select Open Archive... A standard file dialog will be displayed.
3. Locate and select the VCT file containing your bundle updater.
4. Click Open.
5. In the VISE X archive window, select the bundle updater and click the Get Info
button. The bundle updater’s Get Info window will be displayed.
Illustration 19-14: Bundle Updater Get Info window
6. Click the Show Files button in the upper right corner of the Get Info window.
The updater window will be displayed.
7. Make any changes necessary to the Source and Target items.
VISE X User’s Guide
Section 3 Building Updaters
19–22
Building an Updater for an Application Bundle
8. Compare the Source and Target items.
9. Close the updater window and save changes to the bundle updater.
About the Updater
Window
All actions for creating bundle updaters will be performed in the Updater window, which
appears below:
Illustration 19-15: Updater window
The following is a brief description of each item in the window:
Adding Items
■
The Source Items field is where you’ll identify the source (original) items that
are eligible for updating. This field can contain up to eight different source items.
It can display four source items at a time, and will grow as needed.
■
The Target Item field is where you’ll identify the target (new) item, which is the
item the updater should create when updating any item listed in the Source
Items field.
■
The Trash Can allows you to remove items from the source and target item lists
by dragging them over the icon.
■
The Add Item... button lets you add an item to the currently selected field. You
can also add items by drag and drop directly from the Finder.
■
The Show Info button displays an Updater Item Info window.
■
The Compare button becomes active after you have added at least one source
item and one target item. It builds an updater item for the items and options
that you identified.
Each bundle updater must identify at least one source (original) item and one target (new)
item.
Drag and drop is the easiest way to add items to the bundle updater
Source Items and Target Item fields, instead of using the Add Item…
dialog. You can also drag and drop items between fields within the
updater window.
Chapter 19 Building Updaters
VISE X User’s Guide
Building an Updater for an Application Bundle
Adding Source Items to
the Bundle Updater
19–23
To add a source item, perform one of these two procedures:
■
Drag the icon for the item from the Finder into the Source Files field in the
Updater window.
OR
1. Select the Source Items field in the Updater window and then do one of the following:
■
Click Add Item...
■
Double-click the field.
A dialog box will be displayed.
2. Locate and select the desired item.
3. Click Add. The name of the added item will be displayed in the Source Items field.
4. Repeat as needed until all source items are identified. You can identify up to eight
items. The Source Items field will grow as needed to display all the items that you
identify.
Adding Target Items to
the Bundle Updater
The Target Item field can contain only one item. Adding an item to the Target Item field
will replace any item that is already listed there.
To add a target item, perform one of these two procedures:
■
Drag the icon for the item from the Finder into the Target Item field in the
Updater window.
OR
1. Select the Target Item field in the Updater window and then do one of the following:
■
Click Add Item...
■
Double-click the field.
A dialog box will be displayed.
2. Locate and select the desired item.
3. Click Add. The name of the added item will be displayed in the Target Item field.
Removing Items from
the Bundle Updater
VISE X User’s Guide
If you wish to remove a source or target item from the bundle updater, select the item and
drag it over the Trash Can icon at the lower left of the window. When you release the
mouse, the item will automatically be removed.
Section 3 Building Updaters
19–24
The Updater Item
Information Window
Building an Updater for an Application Bundle
The Updater Item Info window displays important information about the items included
in your bundle updater, such as format, size, version and location.
Illustration 19-16: Updater Item Info window
The Item Information window always remembers its position on the screen, so you can
move it to a convenient location and it will always appear there.
To show the Item Information window:
1. Select the Show Info button from the updater window.
2. Click once on an item in the updater window to update the information.
To hide the Item Information window:
■
From the File menu, select the Close command.
OR
■
Building the Bundle
Updater
Click on the close icon of the Updater Item Info window.
Once you’ve identified the source and target items, the next step is to build the bundle
updater. When you build the bundle updater, VISE X compares the source items and target items that you identified and analyzes the differences.
To build your bundle updater:
1. Make sure that you’ve set up the bundle updater as desired.
2. Click Compare. The Comparing Files... window will appear, displaying a progress
gauge. When the Comparing Files... window disappears, the build is complete.
3. Do one of the following:
■
From the File menu, select the Close command.
■
Click on the close icon of the Updater window.
A dialog will give you the option to save changes before closing.
4. Click Save.
Enabling Bundle
Updaters to Find Items
to Update
Chapter 19 Building Updaters
Once you create a bundle updater, you need to make sure it can find the items on the target system that should be updated. This process involves the following steps:
1. Create and set up a Find action to search for the versions of the bundle that you
identified as source items in the Updater window. For example, if your source items
VISE X User’s Guide
Building an Updater for an Application Bundle
19–25
are versions 1.0 and 1.5, and the target item is version 2.0, you would set the Find
action to search for versions greater than or equal to 1.0 and less than 2.0.
Illustration 19-17: Find Action for a Bundle Updater
2. Select the bundle updater, and do the following:
VISE X User’s Guide
■
Use the Install If: popmenu to base the installation/execution of the bundle
updater on the success of the Find action you created.
■
Use the Install To: popmenu to set the installation location as the result of
Section 3 Building Updaters
19–26
Building an Updater for an Application Bundle
the Find action you created.
Illustration 19-18: Bundle Updater Settings
3. Make sure that the Find action item appears before the bundle updater it’s attached
to in the archive window.
Make sure that the bundle updater in the archive has the same name
as the item you wish to update on the target system, as documented
in “Creating a Bundle Updater” on page 19-20. For example, if you
want to update a bundle called MyApp.app on the target system, the
name of the bundle updater in your archive must be MyApp.app.
Modifying an Existing
Updater Item
Chapter 19 Building Updaters
VISE X adds bundle updaters to the archive window as folders that have the same structure as the target item. The folders will contain only the items needed to update existing
versions of the source item(s) to the target version. For example, the folders might include
updater items for items that should change, and Delete actions for items that are no longer needed.
VISE X User’s Guide
Building an Updater for an Application Bundle
19–27
In most cases, there is no need to modify the updater items that VISE X creates for bundle
updaters. However, you can make modifications to settings such as resource exceptions, if
needed.
Any changes that you make to individual updater items will be set
back to their defaults if you rebuild the bundle updater (by comparing source and target items).
To modify an updater item within a bundle updater:
1. Launch VISE X.
2. From the File menu, select Open Archive... A standard file dialog will be displayed.
3. Locate and select the VCT file containing your bundle updater.
4. Click Open.
5. In the VISE X archive window, expand the bundle updater to show its contents, if
needed.
6. Locate the updater item that you want to change.
VISE X User’s Guide
Section 3 Building Updaters
19–28
Building an Updater for an Application Bundle
7. Select the updater item and click the Get Info button. The updater item’s Get Info
will be displayed.
Illustration 19-19: Updater item Get Info window
8. Click the Show Files button in the upper right corner of the Get Info window.
The updater window will be displayed.
9. Make any changes necessary to the updater item.
10. Compare the Source and Target items if necessary.
11. Close the updater window and save changes to the updater item.
Information that you can use to modify an existing updater item is available in the following areas of this chapter:
Accounting for Multiple
Source Items
Chapter 19 Building Updaters
■
“About the Updater Window” on page 19-4
■
“Identifying Resource and Data Fork Exceptions” on page 19-6
■
“Modifying Updater Settings” on page 19-11
If you identified more than one source item for your bundle updater, you will need to
construct your updater logic to search the target system for all versions that are eligible for
updating. One way to do this is to create Find actions for each target item version, and
associate each Find action with its own copy of the bundle updater. In this instance, the
VISE X User’s Guide
Building an Updater for an Application Bundle
19–29
first Find action to appear in the archive would use the original bundle updater, and each
subsequent Find action would use duplicates, or shadows, of the original.
Illustration 19-20: Updater Using Find Actions and Shadow Items
Another way to account for multiple source items is to construct your updater logic with
Jump actions. Rather than having a separate Find action for each source item version that
is eligible for updating, you could have a single Find action that searches for a range of
versions. For example, if your source items are versions 1.0 and 1.5, and the target item is
version 2.0, you would set the Find action to search for versions greater than or equal to
1.0 and less than 2.0.
Next, you would create a Jump action to immediately follow the bundle updater in the
archive window, and set up the Jump action as follows:
VISE X User’s Guide
■
Use the Action Result popmenu to base the execution of the Jump action on the
success of the Find action you created.
■
Use the Jump To popmenu to instruct the installer to move back in the install
Section 3 Building Updaters
19–30
Building an Updater for an Application Bundle
sequence to the Find action you created.
Illustration 19-21: Jump Action
When the updater runs, it will search for bundles on the target system to update. If it
finds an eligible bundle, it will update it, and then look for another bundle to update.
When the updater does not find a bundle to update, it will quit.
The archive in the following illustration uses a Jump action to control updater logic.
Illustration 19-22: Updater Using a Find Action and a Jump Action
Setting the Default
Install Location
Set a Default Install Location so that the updater will default to the folder containing the
items that the user needs to update.
To set the Default Install Location for an installer containing updaters:
1. From the Archive menu, select Installer Settings…
2. In the Installer Settings Interface tab, click the Set Default Install Location button.
Chapter 19 Building Updaters
VISE X User’s Guide
Building an Updater for an Application Bundle
19–31
3. Click Set Default Install Location... and create a Find action item to find a version of your product that is eligible for updating.
Illustration 19-23: Sample Default Install Location
When the customer runs the installer, the default installation location will execute
the Find Action and default the install to the correct location.
Setting Interface
Options
VISE X lets you choose to present a slightly different interface to the customer for installers that contain updater items. The basic differences between an Updater interface and a
regular installer interface are the following:
■
When installing and updating items, the Updater interface displays “Updating” as the progress description. The regular installer interface displays
“Installing” in that situation.
■
For the Select Destination window, the Updater interface displays only the
volume that meets the Install Location criteria you specified. The regular
installer interface displays all available volumes in that situation.
You must have a Default Install Location set before selecting the
updater interface.
To use the Updater interface feature:
1. From the Archive menu, select Installer Settings. The Installer Setting Interface
tab will be displayed.
VISE X User’s Guide
Section 3 Building Updaters
19–32
Building an Updater for an Application Bundle
2. From the Interface popmenu, select Updater.
Illustration 19-24: Setting the Updater Interface
3. When you are finished, click OK.
4. To build the installer, click the File menu and select Build Installer…
Updater Interface
When you choose to display an “Updater” interface, the built installer will be similar to
the following example.
For the opening window, the updater displays an informative Read Me file that explains
what will happen as a result of the update. (The Read Me is optional.) At this point, the
Chapter 19 Building Updaters
VISE X User’s Guide
Building an Updater for an Application Bundle
19–33
only visible difference between the Updater interface and the regular installer interface is
the dimmed progress bullet that reads “Updating” rather than “Installing.”
Illustration 19-25: Installer with Updater Interface
After the customer clicks Continue, the updater displays the Select Destination window.
Here the updater displays only the volume that meets the Install Location criteria you
specified. The regular installer interface displays all available volumes in this case.
Illustration 19-26: Updater Select Destination window
VISE X User’s Guide
Section 3 Building Updaters
19–34
Building an Updater for an Application Bundle
When installing and updating items, the Updater interface displays “Updating” as the
progress description. The regular installer interface displays “Installing” in this case.
Illustration 19-27: Updater Updating window
For the window displayed at the end of the update, the only visible difference between the
Updater interface and the regular installer interface is the dimmed progress bullet that
reads “Updating” rather than “Installing.”
Illustration 19-28: Updater Finish Up window
Chapter 19 Building Updaters
VISE X User’s Guide
Building an Updater for an Application Bundle
19–35
If you do not choose the Updater interface, the only visible difference to the customer
between an installer containing updater items and a regular installer is in the progress
gauge. During installation, two bars will be visible (as illustrated below): one for the progress of the general install, and one for the progress of the updates.
Illustration 19-29: Updater dual progress dialog
This type of progress will be displayed whether you choose the Updater interface option
or not.
Setting Auxiliary
Options
Once you've set up your updater to update items, the final step before building the
updater is to set up any auxiliary options. These options can include anything outside of
the standard updater functionality, such as the following examples:
■
Using a custom background image—see “Adding a Background Image” on
page 10-17
■
Suppressing the main updater window (the Installation Type window, which
shows Easy Install and Custom Install options)—see “Choosing Interface Items to
Suppress” on page 10-5
■
Displaying Read Me and License Agreement files—see “Adding Read Me and
License Agreements to the Installer” on page 10-11
■
Installing items in addition to the updated items—see “Adding Files to the
Archive” on page 3-3
■
Adding aliases to the Mac OS X Dock, or to the StartupItems folder—see “Dock/
Startup Items Options” on page 5-43
For the updater examples in this user guide (“The Customer’s Perspective: A Sample Session” on page 17-2 and “Updater Interface” on page 19-32), we used a Read Me file to
instruct the customer on how to select items for updating. Also, we suppressed the main
updater window because there was no need for the customer to select installation type.
VISE X User’s Guide
Section 3 Building Updaters
19–36
Chapter 19 Building Updaters
Building an Updater for an Application Bundle
VISE X User’s Guide
Section 4
Advanced Features
20–1
Chapter 20
Customizing the Archive Window
Archive Window
Overview
Much of the work of building installers takes place in the Archive Window and in the Get
Info windows for individual items. VISE X combines the overall scope of the Archive Window item list with the individualized detail of the Get Info window by allowing you to
customize the archive window detail and column layout. Any field associated with an
archive item can be included in the detail or the columns or both.
Illustration 20-1: Standard Archive Window layout
User-definable Archive
Window Layouts
VISE X User’s Guide
With VISE X you can construct a layout with an arrangement of item detail fields and list
columns which fits the type of installers you need to build. If you do not use Gestalts,
Section 4 Advanced Features
20–2
Archive Window Overview
Languages or Regions, set up a layout without those items. Maybe you need to set Delete
on Uninstall for a number of items in your archive but you’d like an easier way than opening each individual item’s Get Info window. With a custom archive window layout you
can set up a layout which has the Delete on Uninstall field as one of the fields in the list
columns.
Archive Window Layouts
Defined
In VISE X an Archive Window Layout contains the definition for the Item Detail and the
List Columns. Layouts belong to the VISE X application, not any one archive so you will
have identical archive layouts for any archives you open. You may create as many custom
layouts as you wish in addition to the VISE X Standard Layout.
Should you want to have the same layouts on different computers, Archive Window Layouts are stored in the VISE X Layouts file, which can be found in the Preferences folder
for your Mac OS X user account.
Standard Archive Window VISE X has a default archive window layout which cannot be removed or edited. The
archive window illustrated below uses this Standard Layout.
Layout
Illustration 20-2: Archive Window Areas
■
The Item Detail is at the top of the Archive window. The Item Detail contains
data associated with an individual item selected in the Item List. As the selection
in the Item List is changed, the data in the Item Detail changes. Many fields
which were previously only available by opening an item’s Get Info window can
now be placed in the Item Detail of a custom layout.
■
The Vertical Column Titles area contains titles for list columns. This area can
be expanded and collapsed by dragging its bottom separator. When the mouse is
placed over the separator the cursor changes as a visual indicator that the area
can be resized.
■
The Item List contains every file, folder, sub-archive and action item in the
archive. The order of items in the Item List from top to bottom is the order in
which they will be installed or executed in an installer.
Chapter 20 Customizing the Archive Window
VISE X User’s Guide
Defining an Archive Window Layout
■
Defining an Archive
Window Layout
20–3
The List Columns contain data associated with individual items in the Item
List. Many fields which were previously only available by opening an item’s Get
Info window can now be placed in the List Columns of a custom layout. Like
packages, any item in the List Columns which represents a boolean value can be
toggled on or off by clicking in the appropriate cell.
To define an Archive Window layout:
1. Select Customize from the Layout menu.
2. Click the New button on the Layout List dialog.
Illustration 20-3: Layout List
The ordering of items in the Layout List determines the ordering of Layout names
in the Layout menu. The topmost layout is the default layout used for newly created archives. To make a custom layout the default layout, drag the custom layout
by its grab handle to the top of the Layout List.
3. In the Edit Layout dialog Name field, type a name for your new layout.
Illustration 20-4: Layout Name field
VISE X User’s Guide
Section 4 Advanced Features
20–4
Defining an Archive Window Layout
4. In the Edit Layout dialog, select fields to be displayed in the Item Detail and the
List Columns.
Illustration 20-5: Edit Layout window
5. When you have the fields for the Item Detail and the List Columns set up as you
wish, click the OK button. Your layout will be saved and you will be returned to
the Layout List window.
Layout Setup
There are a number of tools at your disposal in the Edit Layout window:
■
Click the upper >> Copy >> button to place the field selected in the Available
Fields scroll list in the Item Detail. Double-clicking on a field in the Available
Fields scroll list will also place the field in the Item Detail.
■
Click the lower >> Copy >> button to place the field selected in the Available
Fields scroll list in the List Columns. Option Double-clicking on a field in the
Available Fields scroll list will also place the field in the List Columns.
■
When a field is selected in either the Item Detail or List Columns scroll list the
corresponding >> Copy >> button changes to Clear. Clicking the Clear button
removes the field from the corresponding scroll list.
■
To move a block of fields to the Item Detail or the List Columns scroll box,
select the first field of the block in the Available Fields scroll box then with the
Shift key held down, select the last field of the block. With the entire block
selected, click the upper or lower >> Copy >> button.
■
To move several discontinuous fields to the Item Detail or the List Columns
scroll box hold down the Command key to select discontinuous fields in the
Available Fields scroll box and click the upper or lower >> Copy >> button.
■
The Insert ¶ button will place a ¶ after the selected field in the Item Detail list.
The ¶ symbol indicates a line break. When the Archive window is made wider
more fields will fit on a single line in the Item Detail unless a field is followed by
a line break. A line break indicates that the field which follows will always be
placed on a new line in the Archive window Item Detail. The line break symbol
Chapter 20 Customizing the Archive Window
VISE X User’s Guide
Layout Samples
20–5
is especially helpful when you wish to give one field in the Item Detail an entire
line. This feature is especially helpful for fields which may have enough data to
fill a line or more (i.e. Packages). See “Layout Samples” on page 20-5 for examples.
■
Fields can be moved up and down by dragging within the Item Detail and List
Columns scroll boxes to change their order in the Archive window.
In addition to determining the data which can be seen in the Archive
Window, Layouts also determine the data arrangement for print routines. Print Window and all Archive Reports except the Diagnostic
Report use the current layout’s column arrangement for printouts.
You may want to design layouts specifically for printing.
Customizing the Layout
Menu
The Layout menu is dynamically created based upon the custom layouts and the ordering
of those layouts in the Layout List. Layouts are automatically numbered with command
key equivalents in the Layout menu.
Layout Separators
To create a separator in the Layouts menu create a new layout and use a single dash (“-”) as
the layout name. Then drag the separator layout in the Layout List to the desired location.
Layouts designated as separators are not given command key equivalents in the Layout
menu.
Default Layout
The default layout is the layout which is listed first in the Layout List. The default layout
will be used when an archive is first opened and when a new VCT is created. To set a layout as the default layout drag the layout name to the top line of the Layout List window.
The Standard Layout
The Standard Layout cannot be edited or deleted.
Layout Samples
Layouts make the Archive window extremely flexible and powerful.
Simple Layout
For the first sample, create a very simple layout containing an Item Detail where Packages
can display on multiple lines.
Illustration 20-6: Edit Layout Item Detail with line breaks
VISE X User’s Guide
Section 4 Advanced Features
20–6
Layout Samples
The resulting Archive window lets you see and work with only the data that you need.
Illustration 20-7: Item Detail displaying effects of line breaks
Columns for Editing
In the sample below, the layout has been customized by adding fields to the List Columns
area.
Illustration 20-8: Archive Window with customized columns
Chapter 20 Customizing the Archive Window
VISE X User’s Guide
Archive Window Shortcuts
20–7
Any column which represents a boolean value can be edited in the List Columns. As
shown in the table below, some settings are not appropriate for some items and are therefor disabled when an item of that type is selected.
Field Applies to:
Files
Folders

Application Bundle
Delete on Uninstalls


File is Invisible

File is Locked


Gestalts


Open After Installing


Packages



Placeholder Folder
Restart After Installing


Use Custom Icon
Symbolic Link

Synchronize Dates


Set Owner To Root


Table 20-1: Editable Archive Window Columns
Expand and Collapse
Column Title Area
The Vertical Column Titles area can be expanded or collapsed by dragging the lower edge
of the title area up or down. When the mouse is in the proper position to expand or collapse the title area the cursor changes to:
Illustration 20-9: Expand/Collapse Column Cursor
Archive Window
Shortcuts
Action
Shortcut
Click on a vertical column title
Selects all items assigned
Command-right arrow
Expands selected folder(s)
Command-left arrow
Collapses selected folder(s)
Option Command right arrow
Expands selected folder(s) and all its subfolders
Table 20-2: Archive Window Shortcuts
VISE X User’s Guide
Section 4 Advanced Features
20–8
Archive Window Shortcuts
Action
Shortcut
Command-A
Selects all items in the item list
Option-Add Button
Use the alternate Add dialog from the
Preference setting
Up arrow
Select previous item above in item list
Down arrow
Select next item below in item list
Enter or Return
Make selected item’s name an editable
field (toggles)
Double-click on a folder while holding
down the ‘D’ key or the ‘d’ key.
Open the default folder settings dialog
for that folder.
Table 20-2: Archive Window Shortcuts
Chapter 20 Customizing the Archive Window
VISE X User’s Guide
21–1
Chapter 21
Advanced Project Management
VISE X contains a number of features which enable high levels of installer project management. Advanced Project Management features include:
■
Build Directives
■
Project Window
■
Build Directives
VISE X User’s Guide
■
Build Source
■
Build Target
■
Archive Links
■
Read Me Files
■
License Agreements
■
Resource Files
■
Billboard Files
■
PlugIns/Scripts
Using VISE X with Source Control
Build Directives allow you to conditionally include or exclude items (folders, files, action
items, and external resource files) from your installer at build time. They are very similar in
functionality to compiler directives in program code. Build Directives may be best understood if contrasted to Packages.
■
Packages serve as limiting agents at installer runtime while Build Directives serve
as limiting agents at installer build time.
■
Packages determine whether the item in the installer will be executed or installed
while Build Directives determine whether the item will even be included at all in
the built installer.
■
Packages allow flexibility at installer runtime so that one installer can cover several install options. Build Directives allow flexibility at installer build time so
that one archive can be used to build multiple installers which share some con-
Section 4 Advanced Features
21–2
Build Directives
tent but each have some different content.
Build Directives serve as limiting agents for an item at installer build time. If no Build
Directives are checked for the item, the inclusion of the file, folder, action item or external
resource file in an installer build will not be limited. Another way to say the same thing
would be – if no items are checked in the Build Directives popmenu, this item will always
be included when an installer is built.
Up to 63 Build Directives can be defined per archive through the Build Directives window.
Illustration 21-1: Build Directives window
Once defined, Build Directives can be assigned to:
■
Action Items
See “Assigning Build Directives to Action Items” on page 5-4
■
Files and Folders
See “Assigning Build Directives to Files and Folders” on page 9-16
■
Packages
See “Package Build Directives” on page 4-17
■
External Resource files assigned through the Project Window
See “Resource Files” on page 21-24
Build Directive assignments are dependent on Build Targets, which
allow you to build multiple installers at once using pre-defined settings. At build time, VISE X will include/exclude archive items based
on the Build Directive settings for each Build Target used. For more
information on Build Targets, see “Build Targets” on page 21-9.
Build Directives and the
Archive Window Item List
Archive items (files, folders and action items) which will not be included in a build performed with the current Build Directive settings are grayed in the Archive Window Item
Chapter 21 Advanced Project Management
VISE X User’s Guide
Build Directives
21–3
List. If your Archive Window layout has been designed with Build Directives as one of the
columns, the active Build Directive(s) will be indicated by a bullet before the name.
Illustration 21-2: Item Dimmed in Archive Window due to Build Directives
Build Directives and the
Project Window
External resource files which will not be included in a build performed with the current
Build Directive settings are grayed in the Project Window.
Illustration 21-3: Item Dimmed in Project Window due to Build Directives
Build Directive Setup
To set up Build Directives for an archive:
1. Add to the archive all files, folders, action items and external resource files for all
installer builds. Your archive should contain a superset of all installer builds.
VISE X User’s Guide
Section 4 Advanced Features
21–4
Build Directives
2. Select Build Directives… from the Archive menu.
3. Enter Build Directive names for each Build Directive you will need.
Illustration 21-4: Enter Build Directive Names
Build Directives are not mutually exclusive. They may be used together. For example, in the illustration above, we may want to build an installer which will include
all items for Debug Build, Basic Install, Deluxe Install, and Deluxe + Fonts. All
Build Directives would be checked in that case. On the other hand, a Basic Debug
installer would be built if only the first two Build Directives were checked.
4. Close the Build Directives window by clicking the OK button.
5. From the Layouts menu, switch to an archive window layout which has Build
Directives in the columns. If you do not have an archive window layout which has
Build Directives in the columns see “Defining an Archive Window Layout” on
page 20-3.
6. Be sure that the active Build Target is the one you wish to associate with these
Build Directives (see “Active Build Target” on page 21-18).
Chapter 21 Advanced Project Management
VISE X User’s Guide
Build Directives
21–5
7. Assign Build Directives to any item which will be limited.
Illustration 21-5: MyApp Archive with Sample Build Directive Setup
Items of note about the sample setup above:
■
The easiest way to understand the Build Directives assignments is to read
across the archive window from item name across to Build Directives assignment.
No Build Directive
Assigned
■
The Find TextEdit Action item is included in all installer builds because it
does not have any Build Directive assignments. Items which will always be
included in any build have no Build Directive assignments (i.e. they are not
limited). The Find action item, the MyApp 2.0 folder, the basic contents of
the MyApp 2.0 folder and the Comment action item do not have a Build
Directive assignment. They form the foundation of all builds of this product
family.
Only One Build Target
■
The Debug Only folder will only be included in a build when the Debug
Build Directive is active (marked by a bullet in the column title area).
AND Conditions
■
The MyApp Deluxe Debug Issues item will only be added to the Debug
Only folder if both the Debug Build AND the Deluxe Install Build Directives are active.
VISE X User’s Guide
Section 4 Advanced Features
21–6
Project Window
OR Conditions (Any Match)
■
Because the Any Match column is checked also, The MyApp Clip Art folder
will be included if either the Deluxe Install OR the Deluxe + Fonts Build
Directive is active.
NEVER Conditions
■
If an archive item has only the Any Match column checked, that item will
never be included in an installer build.
■
The “Last Mod” Comment Action item does not have any Build Directive
assignments, because comments are never included in installer builds. This
comment is being used by the developer to record who last modified the
archive and when.
8. Open the Build Directives window and check the Build Directives which should be
active.
9. Close the Build Directives window.
10. Build the installer.
Using Build Directives, Build Targets and AppleScript you can easily
create an automated installer build system.
Project Window
The Project Window contains an overview of the current installer project.
To access the Project Window:
1. With an archive open, select Show Project Window from the Archive menu.
Chapter 21 Advanced Project Management
VISE X User’s Guide
Project Window
21–7
2. The Project window will be displayed.
Illustration 21-6: Project Window
The Project Window is always titled after the archive. If your archive name is
MyApp.vct the project window for that archive will be titled MyApp.vct Project.
When you have multiple archive windows and multiple project windows open it
can become important to be aware of which project window with which you are
working.
In the illustration above we can see that the Archive.vct project contains:
VISE X User’s Guide
■
5 Build Targets
■
2 embedded VCTs
■
2 Read Me Files (one for the Default Language, one for French)
■
2 License Agreements (one for the Default Language, one for French)
■
2 External Resource files (in this case, files containing one ‘shsc’ resource
each for the purpose of using UNIX shell scripts)
■
2 Billboard Files (one for the Default Language, one for French)
■
2 PlugIns/Scripts items (in this case, one plain text file containing a UNIX
script, and one CFPlugIn, which is a bundle structure)
Section 4 Advanced Features
21–8
Build Sources
Build Sources
Each VISE X archive item stores a path to its source on a hard drive or server. In the
archive, folders can be created within the archive, files can be added to the folders and the
hierarchy within the archive can be changed without necessitating a change in the source
file’s location or hierarchy. Each item knows where its source is regardless of its arrangement within the archive. The structure within the VCT is not forced to match the Finder
structure of the source files.
The Sources window displays source paths for each item that was dragged into the archive.
Paths will be displayed for all unique outermost enclosing folders and individual files that
have their own unique paths. By editing source paths, the archive items can be directed to
point to new source items.
Illustration 21-7: Sources Window
Bring Up To Date and Validate Paths use the paths that appear in the
Sources window to perform their operations.
There are two ways to edit source paths:
■
You can use a standard Find dialog to locate and select new source items.
■
You can use search and replace functionality to update the paths that appear in
the Sources window.
Descriptions of both edit methods follow.
To edit source paths using a standard Find dialog:
1. From the Sources window, select the path that you want to edit.
2. Click Edit Path. A standard Find dialog displays.
3. Locate and select the new source item.
4. From the Store Path popmenu, select how you would like to store the source path.
If you select Relative to .vct, you will need to move the associated source items
Chapter 21 Advanced Project Management
VISE X User’s Guide
Build Targets
21–9
whenever you move the VCT, to avoid breaking the source path. If you select
Absolute Path, you will be able to move the VCT without breaking the source
path, as long as the path is still accessible from the new VCT location.
5. Click Choose.
6. When you are finished editing source paths, click OK to close the Sources window.
To edit source paths using search and replace functionality:
1. From the Sources window, click Search/Replace. The following dialog displays.
Illustration 21-8: Search/Replace Dialog
2. In the Search Text field, enter the text you want to find and replace.
3. In the Replace Text field, enter the text that you want to use as the replacement.
4. Click OK. The Search/Replace dialog closes, and VISE X performs the search and
replace action.
5. When you are finished editing source paths, click OK to close the Sources window.
Build Targets
Build Targets allow you to set up different kinds of installers and to easily switch between
them when building. Build Targets can be used to automate the process of building multiple installers with different settings at once.
Illustration 21-9: Target Window
VISE X User’s Guide
Section 4 Advanced Features
21–10
Build Targets
Attributes tab
Format
Items selected from the Format popmenu control what happens when you select Build
Installer… from the File menu as well as the type of installer which will be built.
Target Format
Explanation
Disk Images
At build, installer disk images based on data from the
Disk Names List are created at the location designated
by the path field. Disk Names are used for disk image
names and Segments are saved within the appropriate
disk image volumes.
Folders/CD Segments
At build, an installer based on data from the Disk
Names List is created at the location designated by the
path field. Disk Names are used for folder names and
Segments are saved within the appropriate disk folder.
CD Installer
(Uncompressed)
At build, a CD installer is created at the location
designated by the path field and files are extracted
from the archive and copied to the same location as
the CD installer.
Application Bundle
At build, a single file application bundle installer
containing compressed archive items is created at the
location designated by the path field. This is the
preferred way to deliver a multi-language installer on
Mac OS X. It allows the proper display of single-byte
and double-byte character sets from within the same
installer.
Web Installer
At build, a web installer and designated group files are
created at the location designated by the path field. If
Upload Cab file(s) to Web Server at Build Time
(FTP sites only) is checked in the Web tab of
Installer Settings, the group file(s) are uploaded to the
web server designated in Download Sites from the
Internet menu.
Web Installer (w/Data)
At build, a web installer (containing all data as if user
had just downloaded it) and designated group files are
created at the location designated by the path field. If
Upload Cab file(s) to Web Server at Build Time
(FTP sites only) is checked in the Web tab of
Installer Settings, the group file(s) are uploaded to the
web server designated in Download Sites from the
Internet menu.
Table 21-1: Build Target Format Options
Chapter 21 Advanced Project Management
VISE X User’s Guide
Build Targets
21–11
A VISE X installer running on Mac OS X can install to a Mac OS X
drive or a Mac OS 9 drive.
Create Debug
Create Debug - controls the inclusion of debug features in a built installer.
Settings
Illustration 21-10: Build Target, Attributes tab, Settings popmenu
Selecting an item from the Settings popmenu allows you to determine the Installer Settings set that will be used for the Build Target. Each Build Target can have its own Installer
Setting or Installer Settings can be shared by different Build Targets.
VISE X User’s Guide
Section 4 Advanced Features
21–12
Build Targets
Display Billboards
Illustration 21-11: Build Target, Attributes tab, Display Billboards
popmenu
Selections from the Display Billboards popmenu determine how the billboards will be displayed.
Display Method
Explanation
Sequentially
Billboards will be displayed in sequence during
the install. Billboard duration can be set per
billboard. If billboard durations exceed actual
install time, some billboards may not be
displayed.
By Disk
Billboards will be displayed by disk during the
install. If a disk is not used during an install, the
billboard assigned to that disk will not be
displayed.
By Package
Billboards will be displayed by package as the
package is installed.
Table 21-2: Billboard Display Methods
Installer Name
The Installer Name field is used to designate the file name for the built installer. The
Installer Name field is only available for the following Build Target formats:
■
CD Installer
■
Application Bundle
■
Web Installer
■
Web Installer (w/Data)
Chapter 21 Advanced Project Management
VISE X User’s Guide
Build Targets
Language
21–13
Selections from the Language popmenu determine which languages this installer will support. The Build Target Language popmenu contains all of the supported languages plus
the last item, Language In Archive.
At installer build, while copying the resources from the Localization File that have been
imported in the Localization window, VISE X will only copy the translated information
for the language(s) checked in the Build Target language popmenu.
The last item, Language In Archive is used when there is only one language in the language file. If it is checked on, the installer will support the language in the VCT plus the
language that has been imported into the Localization file.
CFBundleName
The CFBundleName is the name the Finder displays for the installer in the File menu, and
the name VISE X displays on the installer’s main dialog window. For an example, see the
following illustration:
Illustration 21-12: Installer showing CFBundleName
If you leave the CFBundleName field blank, VISE X will assign CFBundleName the same
name that you used for Installer Name on the Attributes tab. (The Installer Name field
sets the value for CFBundleExecutable within the installer bundle’s Info.plist file.)
The following example shows the contents of an Info.plist file for an installer bundle.
Notice that the values for CFBundleExecutable and CFBundleName are different. In this
case, the installer executable would have the name “My App Installer.” When launched,
the installer would display “Example for showing CFBundleName” in both the File menu
and the main dialog window.
VISE X User’s Guide
Section 4 Advanced Features
21–14
Build Targets
Illustration 21-13: Info.plist showing CFBundleName
Path
The Path determines where the built installer will be saved along with any segments, file
group files, web catalog files and any Finder-draggable files.
Be sure to select a path for built installers that is different from the
path for source files. This becomes especially important for CD
Installers.
Duplicating a build target There may be times when you want to duplicate a build target. For example, you could
duplicate a complex build target and make just one change to the copy so that it creates a
debug installer.
To duplicate a build target:
1. Click on the target name to highlight it.
2. Hold down the Option key and click Add.
Chapter 21 Advanced Project Management
VISE X User’s Guide
Build Targets
21–15
Directives tab
Illustration 21-14: Build Target, Directives tab
When a Build Target is built, Build Directives will be set on or off based upon the settings
in the Build Target Directives tab. This enables Build Targets to automatically include or
exclude files, folders and actions. Using Build Directives and Build Targets, one archive
can be used to build multiple installers with different file sets. For more information see
“Build Directives” on page 21-1.
Post processing tab
Illustration 21-15: Build Target, Post Processing tab
After an installer is built items set in the Post Processing tab enable the automatic creation
and placement of Tarball (.tar.gz) files. The field allows you to pre-determine the Tarball
VISE X User’s Guide
Section 4 Advanced Features
21–16
Build Targets
file name. (The .tar.gz filename extension will be added automatically.) The Edit Path button allows you to determine the Tarball file’s location.
Post processing is only available for the following Build Target formats:
■
Application Bundle
■
Web Installer
■
Web Installer (w/Data)
If you use the Post Processing section of build targets to create a
Tarball (.tar.gz) version of your installer, you should restrict the
Tarball file name to 29 characters or less for compatibility with Mac
OS X versions prior to 10.4. Otherwise, if you make the Tarball name
longer than 29 characters, the uncompressed installer will not launch
on the earlier OS versions. (If you are confident that the installer will
be used on Mac OS X versions 10.4 or greater, you can use up to 31 characters for the
Tarball file name.)
Scripts tab
Illustration 21-16: Build Target, Scripts tab
The Build Target Scripts tab allows you to designate one AppleScript applet to be executed before the target is built and one AppleScript applet to be executed after the target
is built.
Dates tab
VISE X lets you synchronize the dates of specified install items at build time, according to
the target used. You will need to mark the items to synchronize, and set the dates in whatever target you use to build the installer.
To synchronize dates:
1. From the main archive window, double-click on an install item.
Chapter 21 Advanced Project Management
VISE X User’s Guide
Build Targets
21–17
2. Check the check box next to Synchronize Dates to turn it on, and then close the
window.
Illustration 21-17: Document Get Info Window
3. Next, type Command+0 to display the Project Window. Then double-click on the
target that you want to use for this installer.
4. Click on the Dates tab.
Illustration 21-18: Build Target, Dates tab
VISE X User’s Guide
Section 4 Advanced Features
21–18
Build Targets
5. Use the popmenu on the left to set the creation and modification dates. The
default options are Today, Yesterday and Tomorrow, or you can choose Custom to
set a different date.
6. Use the popmenu on the right to set the creation and modification times. The
default options are Current, 8:00 AM, Noon, 5:00 PM and Midnight. You could
also choose Custom to set a different time. When you’re finished, click OK.
7. Build an installer with this target.
Synchronize Dates occurs at build time and will only affect items as
you build them into the installer. The dates of the items in your
archive will remain unchanged.
Active Build Target
Multiple Build Targets can be created. To set a Build Target as the active (current) Build
Target click your mouse to the left of the Build Target icon and name. The active Build
Target is indicated by a bullet symbol (•) Checked Build Targets (√) will all be built whenever a build command is executed.
Illustration 21-19: Multiple Build Targets
Chapter 21 Advanced Project Management
VISE X User’s Guide
Archive Links
21–19
To duplicate a Build Target, select the Target in the Project window,
hold down the option key and click the Add button.
Archive Links
Archive Links displays important information about any embedded VCTs in the archive.
Embedded VCTs are VISE X archives which have been linked to the archive. The files,
packages, gestalts, Build Targets, and external resource files of the embedded VCT become
part of the master archive. In this way, archives can be objects to be used within other
archives.
One department may be working on an archive of sample files, another department on an
archive of ancillary files and applications, and another department may be putting
together an archive containing 3rd party software necessary for successful operation (i.e.
QuickTime, Fonts, Adobe Reader, etc.). All of those endeavors can be going on at once,
separately or together. The Master Installer Builder will be able to create the main archive
with Splash Screen, Billboards, Read Me and License Agreement files and embed the other
archives so that they are combined seamlessly into one archive for building an installer.
VCTs that you embed in your main archive should be no more than
one level deep. In other words, an embedded VCT should not contain another VCT. Embedding VCTs more than one level deep is not
supported and will produce undesirable results.
Embedded VCTs are not compatible between Installer VISE 8.x and
VISE X. Before you can embed an Installer VISE 8.x VCT in VISE X,
you will first need to convert the VCT to VISE X format.
To embed a VCT (with links) in your archive:
1. From the VISE X menu select Preferences. The Preferences dialog will be displayed.
VISE X User’s Guide
Section 4 Advanced Features
21–20
Archive Links
2. In the VCT Link Options panel, if it is not already selected, select Create Links
For.
Illustration 21-20: Preferences - VCT Link Options
3. If they are not already selected, make sure Packages, Gestalts, External Codes
and Build Directives are checked and click OK to close Preferences. When a VCT
is embedded, links will be created for each item checked.
If Don’t Create Links is on in Preferences, any VCT will be added and installed as
a normal file.
4. Add a VCT to your main archive by using the Add… button in the Archive window or by dragging a VCT into the archive window and dropping it in the desired
Chapter 21 Advanced Project Management
VISE X User’s Guide
Archive Links
21–21
location within the item list. Embedded VCTs have bold filenames. Clicking the
twist-down arrow next to an embedded VCT will reveal its contents.
Illustration 21-21: Archive window after embedding VCTs
When a VCT is linked, the embedded VCT’s packages, resource files, gestalts, and
external resource file assignments are added to the master archive.
With the exception of package assignments, an embedded VCT’s files, folders and
action items cannot be edited in the master archive.
5. The Project window will display embedded archives in the Archive Links section.
VISE X User’s Guide
Section 4 Advanced Features
21–22
Archive Links
6. Click the embedded VCT’s twist-down arrow in the Project window to reveal the
package links and resource file links added to the master archive from the embedded VCT.
Illustration 21-22: Project window after embedding VCTs
Chapter 21 Advanced Project Management
VISE X User’s Guide
Read Me Files
21–23
7. If you open the Get Info window for the embedded VCT there is an option entitled, Don’t Copy vct Resources. When checked, the resources for that embedded
VCT will not be copied into the built installer.
Illustration 21-23: Get Info window for Embedded VCT
Read Me Files
All Read Me files which are assigned to the installer in the Installer Settings Text Files tab
are listed in the Project Window Read Me Files section.
Viewing a Read Me File
To view a Read Me File:
1. Select the file name in the Project Window Read Me Files section.
2. Click the View button at the upper right of the Project Window.
License Agreements
All License Agreement files which are assigned to the installer in the Installer Settings Text
Files tab are listed in the Project Window License Agreements section.
Viewing a License
Agreement
To view a License Agreement File:
VISE X User’s Guide
1. Select the file name in the Project Window License Agreements section.
Section 4 Advanced Features
21–24
Resource Files
2. Click the View button at the upper right of the Project Window.
Resource Files
VISE X extensively supports the addition of custom code to perform additional functions
required by your installer. This custom code can be in the following forms:
■
UNIX shell scripts saved as resource files of type ‘shsc’
■
AppleScripts saved as resource files of type ‘scpt’
■
CFPlugIns (file extension .bundle)
■
UNIX shell scripts saved as plain text files
To add resource files of type ‘shsc’ or ‘scpt’ to your archive, you can use the Resource Files
section of the Project Window. For more information, see Chapter 6-Assigning External
Code. Also see “Executing UNIX Scripts From the Installer” on page 26-21.
Billboard Files
In VISE X, billboard files can be assigned to an installer by adding them to the Billboard
Files section of the Project Window. Billboard files added through the project Window
can be assigned Build Targets and Languages.
To add a billboard file to the archive:
1. In the Project Window, select the Billboard Files heading and click the Add button.
Illustration 21-24: Adding a Billboard File
Chapter 21 Advanced Project Management
VISE X User’s Guide
Billboard Files
21–25
2. Locate the external billboard file to add and click the Choose button.
Illustration 21-25: Selecting a Billboard file
By clicking the New File… button, you can create a new billboard file at the location shown.
3. The Billboard File dialog is displayed. If you are using Build Targets, make assignments by making selection(s) from the Build Target popmenu. If the billboard file
has no Build Targets assigned, it will be included in every build.
If the billboard is for a specific language, select the language from the Language
popmenu. This enables the creation of multiple billboard file sets for different languages or even different sets of billboards for the same language.
Illustration 21-26: Setting Build Targets for a Billboard File
4. Click OK to close the Billboard File dialog.
VISE X User’s Guide
Section 4 Advanced Features
21–26
PlugIns/Scripts
For information on Billboard setup see Chapter 11-Adding Billboards to an Installer.
PlugIns/Scripts
VISE X extensively supports the addition of custom code to perform additional functions
required by your installer. This custom code can be in the following forms:
■
UNIX shell scripts saved as resource files of type ‘shsc’
■
AppleScripts saved as resource files of type ‘scpt’
■
CFPlugIns (file extension .bundle)
■
UNIX shell scripts saved as plain text files
To add CFPlugIns or plain text UNIX scripts to your archive, you can use the PlugIns/
Scripts section of the Project Window. For more information, see Chapter 6-Assigning
External Code. Also see “Executing UNIX Scripts From the Installer” on page 26-21.
VISE X and Source
Control
To facilitate the use of VISE X in environments where Source Control is in place, the
builder application includes features to minimize the overhead when checking in an
archive and to recognize and honor a source control system’s file locking mechanisms.
Remove Compressed Data To Remove Compressed Data from an Archive Before Source Control
Check-in:
1. From the File menu select Remove Compressed Data…
2. When the installer is built, VISE X will go out and compress all of the data from
the source files before building the installer segments.
Honoring an Archive’s
Locked State
VISE X will honor a locked state initiated by a source control system. When you open an
archive that has been checked into a source control system but that has not been checked
out for editing you will receive a warning.
Illustration 21-27: Source Control Warning
Chapter 21 Advanced Project Management
VISE X User’s Guide
VISE X and Source Control
21–27
An archive which is part of a source control system but which has not been checked out
for editing is indicated by a lock icon in the status bar at the bottom left of the archive
window.
Illustration 21-28: Archive Window with lock
VISE X User’s Guide
Section 4 Advanced Features
21–28
Chapter 21 Advanced Project Management
VISE X and Source Control
VISE X User’s Guide
22–1
Chapter 22
Using Runtime Variables
Runtime Variables
Runtime variables are placeholders that are filled with values (up to 255 characters) when
the installer is run on the customer’s computer. Runtime variables can be used for text
substitution as well as for program logic.
Runtime variables can be set by:
Using Variables for
Text Substitution
■
Assigning default values in the Variable list
■
Set Variable Action items which execute during installation
■
Form controls (buttons, checkboxes, and radio buttons) which are activated by
user choices in custom dialogs during installation
Runtime variables can be used as placeholders which will be substituted with variable text
when the installer is run. In the following example we will set up and use a variable for
runtime text substitution.
The basic steps for setting up variables for text substitution are:
■
Declare variables and set initial values.
■
Enter variables in desired text areas.
■
If necessary, add Set Variable actions to reset variables to initial values for installers which may be run multiple times without quitting between runs.
Declaring a Variable
To declare a variable and set its initial value:
and Setting Initial Value
1. From the Archive menu select Variables…
2. The Variable List window will be displayed. Click the New button.
VISE X User’s Guide
Section 4 Advanced Features
22–2
Using Variables for Text Substitution
3. In the Edit Variable window type in a variable Name. You may also enter a default
Value for the variable. (The value limit is 255 characters.) If you wish to add an
explanatory comment about the variable you can type that in the Comments field.
Illustration 22-1: Edit Variable
Variable names are case sensitive. %Product% is not the same as
%product%. When testing the value of a variable, however, the test is
not case sensitive, so “Photoshop” is considered the same as “photoShop”.
4. Click OK to close the Edit Variable window.
5. Click OK to close the Variable List window.
Entering Variables in
Text Areas
Variables can be used in a number of locations within the installer. For a complete list of
areas where runtime variable substitutions are valid see Table 22-1, “Valid Archive Areas for
Runtime Variable Substitution,” on page 22-6. Also see “Special Variables” on page 22-7
for information on variables with special uses.
In our example we will enable runtime variable substitution in Easy Install Text and in
Package Name and Description so that the archive we construct can be used to produce
installers for multiple versions of our product with a simple variable value change.
To enter variables in text areas:
1. From the Archive Menu, select Installer Settings.
2. In the Easy Install panel, click on the Edit Easy Install Text button.
3. Type in the text to be displayed for Easy Install. When entering a variable to be substituted at runtime, type a percent sign, followed by the variable name, followed by
Chapter 22 Using Runtime Variables
VISE X User’s Guide
Using Variables for Text Substitution
22–3
a percent sign. %VariableName% is the indicator for a runtime variable.
Illustration 22-2: Entering a runtime variable in Easy Install text
In our example, when the Installer is run, %Vers% will be replaced with the text
“1.1”. Make sure you type the variable name exactly as it is declared in the Edit
Variable dialog.
4. Click OK to close the Edit Easy Install Text window and click OK to save Installer
Settings.
5. To enter variables in descriptive text for packages, from the Archive menu select
Packages to get the Package List.
6. In the Package List, select the New button to create a new package.
VISE X User’s Guide
Section 4 Advanced Features
22–4
Using Variables for Text Substitution
7. In the Edit Package window type in text as it appears in the illustration below.
Illustration 22-3: Edit Package window using variables
Note the use of runtime variables in the Package Description and in the Package
Version fields. When this installer is built and run the text “1.1” will be substituted
for %Vers%.
8. Select OK to close the Edit Package window and OK to close the Package List window.
Chapter 22 Using Runtime Variables
VISE X User’s Guide
Using Variables for Text Substitution
22–5
9. Add files to your archive, assign files to packages, and build the installer to test the
runtime variable substitution.
Illustration 22-4: Installer with Easy Install Text
Select Custom Install in the installer and click the package info button for the
Application Only package to test the variable substitution in the Package Description.
Illustration 22-5: Package Description displaying substituted variable
text
VISE X User’s Guide
Section 4 Advanced Features
22–6
Valid text areas for
variable substitution
Using Variables for Text Substitution
Valid areas for variable substitution are listed in the table below:
Archive Area
Valid for Variable
Substitution
Find Action Item
Search Criteria Name
Search Criteria Type
Search Criteria Creator
User Prompt
Delete Action Item
Search Criteria Name
Search Criteria Type
Search Criteria Creator
User Prompt
Copy Action Item
Search Criteria Name
Search Criteria Type
Search Criteria Creator
User Prompt
New Name
Move Action Item
Search Criteria Name
Search Criteria Type
Search Criteria Creator
User Prompt
Rename Action Item
Search Criteria Name
Search Criteria Type
Search Criteria Creator
User Prompt
New Name
Alias Action Item
Search Criteria Name
Search Criteria Type
Search Criteria Creator
User Prompt
Alias Name
Message Action Item
User Prompt
Button 1 Name
Button 2 Name
Set Variable Action Item
Set Variable To value
Test Variable Action Item
Test Variable Comparison value
Sub-launch Action Item
Search Criteria Name
Search Criteria Type
Search Criteria Creator
Table 22-1: Valid Archive Areas for Runtime Variable Substitution
Chapter 22 Using Runtime Variables
VISE X User’s Guide
Using Variables for Install Logic
22–7
Archive Area
Valid for Variable
Substitution
Edit Text File Action Item
Search Criteria Name
Search Criteria Type
Search Criteria Creator
User Prompt
Search For Text
Text to Add/Append
UNIX Script Action Item
UNIX Script
Packages
Package Name
Package Description
Package Version
Package List Header
Package List Footer
Default Install Location
Search Criteria Name
Search Criteria Type
Search Criteria Creator
Installer Settings
Easy Install Text
Uninstall Text
Create Installation Folder Named
Log File Name
Forms
Static Text Item text
Edit Text Item text
Files
File Name
Table 22-1: Valid Archive Areas for Runtime Variable Substitution
If you need to include a percent symbol in a valid variable substitution field, use %%. At installer runtime, %% will be replaced with %.
For instance, if my Package Description field needs to display,
“MyApp now features 50% faster start-ups,” the field should be set
to “MyApp now features 50%% faster start-ups.” When the installer
is run and the variable is substituted, the resulting string will be
“MyApp now features 50% faster start-ups.”
Special Variables
Using Variables for
Install Logic
VISE X User’s Guide
VISE X recognizes the following variables for use in special install functions:
■
InstallVar. Installers can use the value of this variable to dynamically set install
locations at the time of install. See “Setting Install Locations With Variables” on
page 29-4.
■
ShellVar. Installers can send the value of this variable to a UNIX shell script. See
“Executing UNIX Scripts From the Installer” on page 26-21.
One way to demonstrate the use of variables for install logic is to walk through the use of
variables in a fictional install situation. For the purposes of this example we will step
through the setup of the archive used to create the installer for a multimedia editing application called Multimedia Voyager Pro. Our scenario is as follows:
Section 4 Advanced Features
22–8
Using Variables for Install Logic
The installer for Multimedia Voyager Pro can optionally install a folder of sample
graphics. Because previous installs would have used the same folder name and location, we want to avoid replacing existing graphics files without permission. As a
result, our installer needs to allow the user to choose not only whether the sample
graphics will be installed but also whether the install will replace or rename an
existing Multimedia Sample Graphics folder.
1. The archive window for our finished installer is shown in the illustration below.
Illustration 22-6: Var Logic VCT
If you use an archive window layout which displays Install If, Install To and Replace
options in the columns, the flow of the install can be traced. With a little practice
you should be able to read down through the archive items’ Install If, Install To
and Replace settings to get an overview of the archive’s logic flow. In the following
steps, we’ll walk through the archive one item at a time explaining the details of the
setup. We will start with variable declaration.
2. The Variable setup in the archive:
Variable Name
InstallGraphics
Value
No
Table 22-2: Var Logic VCT Variables
This example required the declaration of just one runtime variable.
The first item in the archive is a Set Variable action item. We start by initializing
our key variable InstallGraphics to “No” so that we can count on a consistent variable value even if the installer is run multiple times in the same session.
Chapter 22 Using Runtime Variables
VISE X User’s Guide
Using Variables for Install Logic
22–9
3. We needed to construct a dialog that would be displayed to the user during the
install which would clearly spell out the graphics install options.
Illustration 22-7: Var Logic Form
Note that the Yes-rename radio button is the default selection and the OK button
is the default button so that the user can accept the choice of the dialog by hitting
the Return or Enter key. Each item in the form layout is listed below with the properties that are important for our example.
Var Logic
Form Item
Properties
Picture
Res ID 959
Static Text
Text asking user for input.
Radio Group
Name: Sample Graphics Install Options
Title: Sample Graphics Install Options
Set Variable: InstallGraphics
Radio Button
Name: Rename
Title: Yes - rename existing sample graphics
Default On: Checked
Radio Button
Name: Replace
Title: Yes - replace existing sample graphics
Default On: Unchecked
Radio Button
Name: No
Title: No
Default On: Unchecked
Button
Title: OK
Default button: On
Behavior: Continue
Table 22-3: Var Logic Form Items
VISE X User’s Guide
Section 4 Advanced Features
22–10
Using Variables for Install Logic
Note that the Radio Group item sets the variable InstallGraphics.
None of the individual radio buttons are configured to set a variable.
When the OK button is clicked (since it has a behavior of Continue),
the InstallGraphics variable will be set to the Name of the highlighted radio button. It is important to note that each of the radio
button Names differ from their Titles. The Test Variable actions
which follow this form will test the InstallGraphics variable for the
values “Rename,” “Replace” or “No” rather than “Yes - rename existing sample graphics,” “Yes - replace existing sample graphics” and “No.”
4. Each root level item in the archive is listed below with a description of the item’s
function and/or properties.
Archive Item
Item Type
Description
Initialize
InstallGraphics
Set Variable
Action
Set InstallGraphics variable to “No.” Provides
initial variable value and resets variable if users
do multiple installs without quitting.
Multimedia
Voyager Pro
Application
Folder
Install items
Install Sample
Graphics?
Form Action
Set the InstallGraphics variable based upon user
selection of options.
Rename
Graphics
Test Variable
Action
Test the InstallGraphics variable to determine if it
equals “Rename.”
Replace
Graphics
Test Variable
Action
Test the InstallGraphics variable to determine if it
equals “Replace.”
Multimedia
Sample Graphics
Folder
If the InstallGraphics variable equals “Rename”
then install this folder.
Install If: Rename Graphics variable test is TRUE.
Install To: Local Domain, Applications
Replace: Always, Rename Existing
Multimedia
Sample Graphics
Folder
If the InstallGraphics variable equals “Replace”
then install this folder.
Install If: Replace Graphics variable test is TRUE.
Install To: Local Domain, Applications
Replace: Always
Table 22-4: Var Logic Archive Item Descriptions
Chapter 22 Using Runtime Variables
VISE X User’s Guide
23–1
Chapter 23
Localization
Creating Installers
in Different
Languages
VISE X’s localization features allow you to create installers for different languages in
which:
■
The localized archives contain file names, package names and descriptions, and
Easy Install text in the new language, while the files’ assignments to packages,
disk information, gestalts, replace options, etc., are the same as the original
archive. You do not have to recreate the entire archive in the new language.
■
The language of the windows, buttons and dialogs of the installer itself are in the
new language.
You can create installers that are localized for a single language (such as a French-only
installer) or installers that can handle more than one language (such as a French-English or
a French-English-German installer).
MindVision Installer
Language Files
All Installer language files, including language files you may construct yourself, must be
stored in the VISE X Languages folder. That folder is located within the builder’s application bundle at: VISE X.app/Contents/Resources/VISE X Languages.
Language files in the VISE X Languages folder can be selected from the Language popmenu in the Installer Settings Interface tab. The Language file selected in the Installer Settings Interface tab controls the language of the windows, buttons and dialogs of the
installer.
MindVision Installer language files are currently available for:
Chinese (Simplified)
Chinese (Traditional)
Danish
Dutch
English
Finnish
French
German
Italian
Japanese
Korean
Norwegian
Portuguese (European)
Spanish
Swedish
Since languages are constantly being added, you may wish to check with MindVision if
you do not see a language on this list that you need.
VISE X User’s Guide
Section 4 Advanced Features
23–2
Supported Languages
About the Localization Process
VISE X contains an easy method for creating as many localized versions of your software
as you desire.
The following languages are supported:
Albanian
Arabic
Chinese (Simplified)
Chinese (Traditional)
Croatian
Danish
Dutch
English
Estonian
Faeroese
Finnish
Flemish
French
About the
Localization Process
German
Greek
Hebrew
Hindi
Hungarian
Icelandic
Irish
Italian
Japanese
Korean
Lappish
Latvian
Lithuanian
Maltese
Norwegian
Persian
Polish
Portuguese
Russian
Spanish
Swedish
Thai
Turkish
Urdu
The localization process is directed through the Localization window and uses four types
of files. It is important to understand what these files are and how they are used for localization.
File
Icon
Description
Localization file
Used to store localized resources.
Translator
application
Application that early VISE X versions could create
for translation purposes. VISE X versions 1.5 and
later support creating a translator as an XML file
only. The ability to import data from translator
applications is retained for legacy purposes.
Translator XML
file
XML file created by VISE X used to isolate and
collect resources for files, package names and other
items added to the archive by the developer. The
XML file is formatted as an Apple property list (file
extension .plist), so it can be opened and edited
using Apple’s Property List Editor (a utility
included with Apple's Developer Tools). Also, the
file is plain Unicode text, which can be edited using
any text editor.
Language file
Localized VISE X resources provided by
MindVision for installer interface elements.
Table 23-1: Localization file types
How you create a localized installer depends on whether your installer will be:
Chapter 23 Localization
VISE X User’s Guide
About the Localization Process
Single-language
Installers Overview
23–3
■
A single-language installer (e.g., a French-only installer); or
■
Aa multi-language installer (e.g., a French-English Installer or a French-EnglishGerman installer).
Overview of the steps to create a single-language installer:
1. Set up and finalize archive files, packages, action items, etc.
2. Create Translator.
3. Send Translator out for translation or translate in-house.
4. Create Localization File.
5. Import Translator data into Localization file.
6. Set Language in Installer Settings Interface tab.
7. For each Build Target to be used, set Languages in Target Attributes tab.
8. Build single-language installer.
Multi-language
Installers Overview
Overview of the steps to create a multi-language installer:
1. Set up and finalize archive files, packages, action items, etc.
2. Create a Translator for each language to be supported.
3. Send Translator out for translation or translate in-house.
4. Create Localization File.
5. For each Translator created in step 2, import Translator data into the Localization
file.
6. Import VISE X language File data for languages to be supported.
7. Add any other necessary resource items to the Localization file.
8. Set Default Language in Installer Settings Interface tab.
9. For each Build Target to be used, set Languages in Target Attributes tab.
10. Build multi-language installer.
VISE X User’s Guide
Section 4 Advanced Features
23–4
Single-Language vs.
Multi-Language
Installers
Creating Single-Language Installers
The procedure to create an installer that only supports a specific language (such as a
French-only installer) is somewhat different than the procedure to create a multi-language
installer (such as an English-French installer or an English-French-German installer).
Use the following table to determine how to build your installer:
To create a…
Put these resources in
the localization file…
…and select this Language
file at the Installer
Settings/Interface tab
Single-language
installer
• Translator for the desired
foreign language
• and any localized external
code resources
Installer file for desired language
Multi-language
installer
• Translators for each
language,
• and resources of the
Installer file for each foreign
language.
The Installer file for the desired
default language. For example, to
create a French-English installer
that defaults to English if the
language of the operating system
is not English or French, select
the English Installer file.
Table 23-2: Creating Single and Multi-Language Installers
Installing Items with
UTF-8 Encoding
VISE X can apply UTF-8 encoding to the names of files and folders you install. This
encoding enables the file names to display correctly on systems running a language different than the target language. For example, a file name in a language with double-byte character sets — such as Japanese — would display correctly on a system running a language
with single-byte character sets — such as English.
When you add files or folders to an archive, VISE X checks to see if the file names are longer than 31 characters, or if they include high ASCII characters. If either condition is true,
VISE X applies UTF-8 encoding to the file names.
To check whether VISE X has applied encoding to a file or folder name, you can view the
archive item's Get Info window. If encoding has been applied, the Long Name field will
contain the item name.
Creating
Single-Language
Installers
To create a single-language installer:
1. Create and set up your archive with all packages, files and action items as they will
be in the final installer. The localization process assumes a complete installer with
which to begin.
2. Select Localization… from the Extras menu.
3. You must create a translator for the language you wish to support. The translator
lets you enter the names of the files, packages, Easy Install text, and disks in the
archive in the new language.
You may import the resources of the translator into a localization file for the
archive, allowing you to keep the archive in your native language while creating an
installer that supports another language.
Chapter 23 Localization
VISE X User’s Guide
Creating Single-Language Installers
23–5
In the Localization Window, select Create New Translator.
Illustration 23-1: Localization Window
Create a Translator
4. In the Create Translator dialog, make the appropriate selections from the Source
Language and Target Language popmenus and the Use source language as
default translation checkbox.
Illustration 23-2: Create Translator dialog
For example, if your archive is in English, select English from the Source Language
popmenu. The translator created will contain all items in the source language that
need to be translated into the target language. From the Target Language popmenu select the language to which you wish to translate your installation.
If you select Use source language as default translation., items to be translated
will appear in the source language, so you can select and modify the text for the
new language. Otherwise, if you do not select this option, items to be translated
will contain no text.
VISE X User’s Guide
Section 4 Advanced Features
23–6
Creating Single-Language Installers
5. Click Create. A standard Save File dialog will be displayed. Save the translator at
your desired location. The default name will reflect the source and target language
selections made in the Create Translator dialog.
Illustration 23-3: Save Translator
Enter Localization
Information in the
Translator XML File
To enter localization information for your installer:
6. Open the translator XML file using the editor of your choice. The examples below
show TextEdit and Apple’s Property List Manager.
Illustration 23-4: Translator XML in TextEdit
Chapter 23 Localization
VISE X User’s Guide
Creating Single-Language Installers
23–7
Illustration 23-5: Translator XML in Property List Editor
7. For each Source key in the file that has a value, enter the new language translation
in the accompanying Target key string.
Illustration 23-6: Editing a Target Key String in TextEdit
Illustration 23-7: Editing a Target Key String in Property List Editor
8. When you have entered all the information in the translator XML file, save and
close the file.
VISE X User’s Guide
Section 4 Advanced Features
23–8
Create a Localization
File
Creating Single-Language Installers
To create a localization file:
9. In the Localization Window, click the Localization File Select button. Rather than
selecting an existing localization file, we will make a new one.
Illustration 23-8: Creating New Localization File
10. A standard Save File dialog will be displayed. Click the New Localization File…
button.
Illustration 23-9: Creating New Localization File
Chapter 23 Localization
VISE X User’s Guide
Creating Single-Language Installers
23–9
11. Name the new localization file and click the Create button.
Illustration 23-10: Naming New Localization File
12. The archive’s localization file name will be displayed in the Localization window
next to the Select button as well as in the Installer Settings’ Advanced tab.
Illustration 23-11: Localization File Created
This localization file will contain all translation items, VISE X Language File items
and any other resource file items you designate.
The archive’s localization file name will also be displayed in the Installer Settings’
Advanced tab.
Illustration 23-12: Localization File Displayed
VISE X User’s Guide
Section 4 Advanced Features
23–10
Import Translator File
Resources
Creating Single-Language Installers
To Import the translator file for the new language into the localization
file:
13. Click the Translator Import button.
Illustration 23-13: Selecting Translator File
14. Navigate to the correct Translator file. Select the correct language and then click
the Choose button.
Illustration 23-14: Selecting Translator File for Import
Chapter 23 Localization
VISE X User’s Guide
Creating Single-Language Installers
23–11
15. The Localization window will display translated items by bullets.
Illustration 23-15: Localization Display
16. Click Done to close the Localization window.
Select Installer
Language
17. Open Installer Settings.
18. In the Installer Settings Interface tab, use the Language popmenu to select the target language installer file.
Illustration 23-16: Setting Installer Interface Language
19. Click OK to close Installer Settings.
Select Language for
Build Target(s)
VISE X User’s Guide
20.Select Show Project Window from the Archive menu. The Project window displays.
Section 4 Advanced Features
23–12
Creating Multi-Language Installers
21. Click to select a Target that you will use for this installer build. Then click the Edit
button. The Target window displays.
22.In the Attributes tab, use the Languages popmenu to select the target language.
Illustration 23-17: Target window, Languages popmenu
23.Click OK to close the Target dialog.
24.Repeat steps 21 through 23 for each Target that you will use.
25.Build your single-language installer.
When you complete step 22 in the preceding instructions, an alternative is to select Language in Archive instead of the target language.
For more information, see “Language” on page 21-13.
If you do not need to create a multi-language installer, you can skip to “Localizing the
Installer Window Title” on page 23-23.
Creating
Multi-Language
Installers
To create a multi-language installer:
1. Create and set up your archive with all packages, files and action items as they will
be in the final installer. The localization process assumes a complete installer with
which to begin.
2. Select Localization… from the Extras menu.
3. Create a translator for each language you wish to handle. Each translator allows the
entry of the names of the files, packages, Easy Install text, and disks in the archive
in one new language.
Chapter 23 Localization
VISE X User’s Guide
Creating Multi-Language Installers
23–13
After translation, you will import the resources of each translator into a localization
file for the archive.
In the Localization Window, select Create New Translator.
Illustration 23-18: Localization Window
Create a Translator
4. In the Create Translator dialog, make the appropriate selections from the Source
Language and Target Language popmenus and the Use source language as
default translation checkbox.
Illustration 23-19: Create Translator dialog
For example, if your archive is in English, select English from the Source Language
popmenu. The translator created will contain all items in the source language which
need to be localized into the target language. From the Target Language popmenu select the language to which you wish to translate your installation.
If you select Use source language as default translation., items to be translated
will appear in the source language, so you can select and modify the text for the
new language. Otherwise, if you do not select this option, items to be translated
will contain no text.
VISE X User’s Guide
Section 4 Advanced Features
23–14
Creating Multi-Language Installers
5. Click Create. A standard Save File dialog will be displayed. Save the translator at
your desired location. The default name will reflect the source and target language
selections made in the Create Translator dialog.
Illustration 23-20: Save Translator
6. Repeat steps 3 through 5 for each language the installer will support.
Enter Localization
Information in Each
Translator XML File
To enter one language’s localization information for your installer:
7. Open the translator XML file using the editor of your choice. The examples below
show TextEdit and Apple’s Property List Manager.
Illustration 23-21: Translator XML in TextEdit
Chapter 23 Localization
VISE X User’s Guide
Creating Multi-Language Installers
23–15
Illustration 23-22: Translator XML in Property List Editor
8. For each Source key in the file that has a value, enter the new language translation
in the accompanying Target key string.
Illustration 23-23: Editing a Target Key String in TextEdit
Illustration 23-24: Editing a Target Key String in Property List Editor
9. When you have entered all the information in the translator XML file, save and
close the file.
VISE X User’s Guide
Section 4 Advanced Features
23–16
Creating Multi-Language Installers
10. Repeat steps 7 through 9 for each translator XML file.
Create a Localization
File
To create a localization file:
11. In the Localization Window, click the Localization File Select button. Rather than
selecting an existing localization file, we will make a new one.
Illustration 23-25: Creating New Localization File
12. A standard Save File dialog will be displayed. Click the New Localization File…
button.
Illustration 23-26: Creating New Localization File
Chapter 23 Localization
VISE X User’s Guide
Creating Multi-Language Installers
23–17
13. Name the new localization file and click the Create button.
Illustration 23-27: Naming New Localization File
14. The archive’s localization file name will be displayed in the Localization window
next to the Select button as well as in the Installer Settings’ Advanced tab.
Illustration 23-28: Localization File Created
By completion, this localization file will contain all translation items, VISE X Language File items and other resource file items for all languages supported by this
installer.
The archive’s localization file can also be set or removed in the Installer Settings’
Advanced tab.
Illustration 23-29: Localization File Displayed
VISE X User’s Guide
Section 4 Advanced Features
23–18
Import Multiple
Translator File
Resources
Creating Multi-Language Installers
To Import translator file resources into the localization file:
15. Click the Translator Import button.
Illustration 23-30: Selecting Translator File
16. Navigate to the first Translator file. Select the correct language and then click the
Choose button.
Illustration 23-31: Selecting Translator File for Import
17. Repeat the import process for each translator file.
Chapter 23 Localization
VISE X User’s Guide
Creating Multi-Language Installers
23–19
18. The Localization window will display translated items by bullets.
Illustration 23-32: Localization Display
Import Multiple VISE X
Language Files
19. For each language this installer will support, import the appropriate VISE X Language file. Select the VISE X Language File Import button.
Illustration 23-33: Import VISE X Language Files
20.Navigate to the location of your language files and select the Installer language file
to import. If you received the language files from MindVision, they will be located
in the VISE X Languages folder. That folder is located within the builder’s applica-
VISE X User’s Guide
Section 4 Advanced Features
23–20
Creating Multi-Language Installers
tion bundle at: VISE X.app/Contents/Resources/VISE X Languages. (VISE X will
direct you to the VISE X Languages folder by default.)
Illustration 23-34: VISE X Languages folder
MindVision’s French language file is named “French Installer;” the Japanese language file is named “Japanese Installer;” etc.
Chapter 23 Localization
VISE X User’s Guide
Creating Multi-Language Installers
23–21
21. With the installer language file selected, select the correct language from the Language popmenu. Then click the Choose button to import the installer language
file into the localization file.
Illustration 23-35: Selecting a VISE X Installer Language File for Import
22.A bullet appears below the User column for the imported language.
Illustration 23-36: Localization Window After Language File Import
23.Repeat steps 19 through 21 for each language supported by the installer.
Select Installer
Default Language
VISE X User’s Guide
24.Open Installer Settings.
Section 4 Advanced Features
23–22
Creating Multi-Language Installers
25.In the Installer Settings Interface tab, use the Language popmenu to select the
default language installer file.
Illustration 23-37: Setting Installer Default Language
The installer default language is the language the installer will default to if the language of the operating system is not one of the languages supported by the
installer. In our example above, the installer will support French, German, and Italian. When run on a French operating system, the installer’s interface items will
appear in French. When run on a German operating system, the installer’s interface
items will appear in German. When run on an Italian operating system, the
installer’s interface items will appear in Italian. When run on an operating system
other than French, German, or Italian the installer’s interface items will appear in
English.
26.Click OK to close Installer Settings.
Select Languages for
Build Target(s)
27. Select Show Project Window from the Archive menu. The Project window displays.
28.Click to select a Target that you will use for this installer build. Then click the Edit
button. The Target window displays.
Chapter 23 Localization
VISE X User’s Guide
Creating Multi-Language Installers
23–23
29.In the Attributes tab, use the Languages popmenu to select the target languages.
Illustration 23-38: Target window, Languages popmenu
Select Mac OS X
Options for Build
Target(s)
30.If the Target will build a multi-language installer for Mac OS X, consider building
the installer as a Mac OS X application bundle to allow proper display of character
sets. (See “About Multi-Language Installers on Mac OS X” on page 23-23 .) To create the application bundle, use the Format popmenu in the Attributes tab to select
Application Bundle (which is the default setting).
31. Click OK to close the Target dialog.
32.Repeat steps 28 through 31 for each Target that you will use.
33.Build your multi-language installer.
About Multi-Language
Installers on Mac OS X
As noted in step 30 in the preceding instructions, VISE X can build a single-file installer as
a Mac OS X application bundle. This is the preferred way to deliver a multi-language
installer on Mac OS X. It allows the proper display of single-byte and double-byte character sets from within the same installer.
Localizing the Installer
Window Title
As a final step after you build your single-language or multi-language installer, you can
localize the installer window title if desired. Localizing this title requires a manual process
outside the realm of building the localized installers with VISE X.
To localize the installer window title:
1. Locate the installer executable. If you built the localized installer with Disk Images
or Folders formats, you will need to open parent folders to locate this file.
VISE X User’s Guide
Section 4 Advanced Features
23–24
Creating Multi-Language Installers
2. From the Finder, right-click on the installer executable and then select Show Package Contents.
3. Open the Contents folder.
4. Open the Resources folder.
5. For each <Language>.lproj folder within the Resources folder, do the following:
1. Using an editor such as TextEdit or Apple’s Property List Manager, create a
Property List file named InfoPlist.strings. Another option is to copy an InfoPlist.strings file from another application and edit that file.
2. Add the key CFBundleName to the InfoPlist.strings file.
3. Assign to CFBundleName the value of the localized text that you want to
use for the installer window title. For instance, if you are creating the InfoPlist.strings file for inclusion in a Swedish.lprof folder, you should assign
localized Swedish text to CFBundleName.
4. Save the InfoPlist.strings file in the appropriate <Language>.lproj folder.
5. Close all folders that you opened to show the installer executable’s package contents.
6. Test your installer.
About Localized
External Code in
Localized Installers
You may include localized external code in a single or multi-language installer. For example, if your installer requires external code that displays a custom dialog box to the user,
you may create a localized version of that resource for each language you wish to support.
There are two ways to include localized external code resources in foreign language installers. The method you use depends on the kind of installer you are creating.
If your installer only contains one language (such as a French-only installer), you may
import the resource into the localization file, or paste the resource into the language
installer file.
If your installer contains more than one language (such as an English-French installer),
you must paste the resource into the language installer file, as you can only specify one
kind of USER resource for each language and the inclusion of the installer language file
resources is crucial.
Exporting User Resources
If you wish to export the resources identified as USER:
1. In the Localization window, select the line containing the USER resources you wish
to export.
2. Click the VISE X Language File Export button. You’ll be asked to identify a name
and location for the resource file.
Updating User Resources
If the source file containing USER resources has been changed, you can easily update the
resources in the archive.
To do so, follow this step:
1. In the Localization window, select the line containing the USER resources you wish
to update.
1. Click the VISE X Language File Update button. If any files containing USER
resources have been changed, you’ll be asked if you want to update the resources in
the language file.
Chapter 23 Localization
VISE X User’s Guide
Creating Multi-Language Installers
Checking the Consistency
of Translator Files
23–25
The consistency check makes sure that a translator file that you imported contains information for all the files, packages, disk names and text in the current archive.
To check the consistency of a translator file:
1. In the Localization window, select the line for the language whose translator you
wish to verify.
2. Click the Check Consistency button.
If the information that was imported from the translator file matches all the items in the
archive, a message “There are no inconsistencies to report” will be displayed.
If the information that was imported from the translator file does not match all the items
in the archive, the Consistency Information window will be displayed:
Illustration 23-39: Consistency Information
This window contains information about inconsistencies between the archive and the
translator. If inconsistencies exist, you should export a new translator, as described below;
enter translation information for the new items in the archive; and import the updated
translator file for the language, replacing the current one for that language.
Exporting Translator Files
If the files or packages in the archive have changed and you wish to
export a translator file containing the new information:
1. At the Language File Setup window, select the line for the language whose translator you wish to export.
2. Click Export.
3. Choose a name and location for the newly exported translator, and click Save.
A new translator file will be created, using the selected language as the destination language. Existing translations for items in the archive will be preserved in the new translator,
but new items in the archive will appear in the translator file as blank.
Importing Other
Resources
VISE X User’s Guide
The Import button in the Other Resources of the Localization window allows the merging of a selected file’s resources into the localization file for that language.
Section 4 Advanced Features
23–26
Localized-at-Install Applications
For example, start by importing the French Installer file by selecting Import in the VISE
X Language File area of the Localization window. Then click the Import button in the
Other Resources area of the Localization window and select a resource file that has some
localized external codes for French. The resources from the resource file selected will be
merged into the data of the previously imported French Installer file. The original French
Installer file is not modified, the copy of that file stored inside the Localization file is
modified.
Localized-at-Install
Applications
If desired, you can use VISE X to install applications which are localized on-the-fly during
the installation process. Instead of including a localized version of the application for each
language in the installer, you can set VISE X to evaluate the language of the customer’s
operating system and merge the appropriate language resources into the application at the
time of installation.
To create an installer with Localized-at-Install Applications:
1. Save your application as just the code and other non localizable resources, without
any localized information in it for any language, and add it to the archive.
2. Create separate resource files containing only the localizable resources for the languages you wish to support, such as Spanish Resources, French Resources, and German Resources files.
3. Assign the language to the appropriate resource files
4. For each resource file:
■
Select the resource file in the archive.
■
From the Install to: popmenu, select Other...
■
Select the language-free application as the target of the merge.
When the installer is launched, the operating system in use will be determined by
the language check, and the application and the appropriate language-specified
resource file will be installed. Both files will be opened, and the resources from the
resource file will be copied to the application. Then, the resource file will be
deleted.
Overriding Dynamic
Localization
In some cases, you may wish to allow the customer to override the dynamic localization
option and choose a language other than the language of their operating system.
Override by User Entry at
Startup
To dynamically override operating system language/region:
1. Launch Installer
2. Immediately after launching hold down the Control and Option keys. Two beeps
will be heard.
3. Enter two digit code for language.
For language codes see Table 23-3, “Language Codes for VISE X,” on page 23-27.
Only numbers 0-9 are accepted, typing letters will result in a beep.
4. Enter two digit code for region
For region codes see Table 23-4, “Region Codes for VISE X,” on page 23-28.
Only numbers 0-9 are accepted, typing letters will result in a beep.
5. Debug installers will display the Language and Region codes in the Debug window.
Chapter 23 Localization
VISE X User’s Guide
Language Codes for VISE X
Language Codes for
VISE X
23–27
VISE X Language codes correspond to Apple’s Language Codes as defined in Inside Macintosh/Text/Chapter 6: Script Manager/Script Manager Reference/Constants/Language
Codes. In the table below languages are arranged alphabetically for ease of use.
Language
Code
Language
Code
Albanian
36
Lettish
28
Amharic
85
Lithuanian
24
Arabic
12
Macedonian
43
Armenian
51
Malagasy
93
Assamese
68
Malay
83
Azerbaijani
49
Malay
84
Azerbaijani
50
Malayalam
72
Bengali
67
Maltese
16
Bulgarian
44
Marathi
66
Burmese
77
Moldovan
53
Byelorussian
46
Mongolian
57
Chewa
92
Mongolian
58
Chinese (simplified)
33
Nepali
64
Chinese (traditional)
19
Norwegian
09
Croatian
18
Oriya
71
Czech
38
Pashto
59
Danish
07
Polish
25
Dutch
04
Portuguese
08
English
00
Punjabi
70
Esperanto
94
Romanian
37
Estonian
27
Ruanda
90
Faeroese
30
Rundi
91
Farsi
31
Russian
32
Finnish
13
Sanskrit
65
Flemish
34
Serbian
42
French
01
Sindhi
62
Galla
87
Sinhalese
76
Table 23-3: Language Codes for VISE X
VISE X User’s Guide
Section 4 Advanced Features
23–28
Region Codes for VISE X
Language
Code
Language
Code
Georgian
52
Slovak
39
German
02
Slovenian
40
Greek
14
Somali
88
Gujarati
69
Spanish
06
Hebrew
10
Swahili
89
Hindi
21
Swedish
05
Hungarian
26
Tagalog
82
Icelandic
15
Tajiki
55
Indonesian
81
Tamil
74
Irish
35
Telugu
75
Italian
03
Thai
22
Japanese
11
Tibetan
63
Kannada
73
Tigrinya
86
Kashmiri
61
Turkish
17
Kazakh
48
Turkmen
56
Khmer
78
Ukrainian
45
Kirghiz
54
Urdu
20
Korean
23
Uzbek
47
Kurdish
60
Uzbek
47
Language of Lapps/Sami
29
Vietnamese
80
Lao
79
Yiddish
41
Table 23-3: Language Codes for VISE X
Region Codes for
VISE X
VISE X Region codes correspond to Apple’s Region Codes as defined in Inside Macintosh/Text/Chapter 6: Script Manager/Script Manager Reference/Constants/Region Codes.
In the table below regions are arranged alphabetically for ease of use.
Region
Code
Region
Code
Australia
15
Israel
13
Croatian system for
Yugoslavia
25
Italy
04
Cyprus
23
Japan
14
Table 23-4: Region Codes for VISE X
Chapter 23 Localization
VISE X User’s Guide
Languages as Defined in Apple’s Script.h File
23–29
Region
Code
Region
Code
Denmark
09
Korea
51
Estonia
44
Lapland
46
Faeroe Islands
47
Latvia
45
Finland
17
Lithuania
41
France
01
Malta
22
French Canada
11
Netherlands
05
French for Belgium and
Luxembourg
06
Pakistan
34
French for Switzerland
18
People's Republic of China
52
German for Switzerland
19
Poland
42
Germany
03
Portugal
10
Great Britain
02
Russia
49
Greece
20
Sweden
07
Hindi system for India
33
Taiwan
53
Hungary
43
Thailand
54
Iceland
21
The Arabic world
16
Iran
48
Turkey
24
Ireland
50
United States
00
Table 23-4: Region Codes for VISE X
Override by External Code VISE X allows you to build an installer that lets the customer choose the install language;
however, you’ll need to write external code to handle the input.
The external code must be in the form of a CFPlugIn named DynamicXCod.bundle.
(See also “CFPlugIn Names for Specialized Functions” on page 26-18.) The installer will
look for this resource as soon as the installer is launched, and before the install window is
created. If this resource is found, the code will be called.
The selector passed in the paramblock is 7. If you want to override the default language,
set the paramblock ->itemHit field to the number of the language you wish to use as
defined in Apple’s Script.h file. (The contents of the Script.h file are listed at the end of
this chapter.)No other fields in the paramblock are valid at this time.
Languages as
Defined in Apple’s
Script.h File
VISE X User’s Guide
The following is a list of the languages as defined in Apple’s Script.h file. The number in
the right-hand column is the one that you should use to identify the language for the purposes described above.
Section 4 Advanced Features
23–30
Languages as Defined in Apple’s Script.h File
To make it easier to find the desired language, this table is organized
alphabetically by language, not numerically by the numbers in the
file.
For This Language…
Use This Number:
Albanian
00000024
Arabic
0000000C
Chinese (Simplified)
00000021
Chinese (Traditional)
00000013
Croatian
00000012
Danish
00000007
Dutch
00000004
English
00000000
Estonian
0000001B
Faeroese
0000001E
Farsi
0000001F
Finnish
0000000D
Flemish
00000022
French
00000001
German
00000002
Greek
0000000E
Hebrew
0000000A
Hindi
00000015
Hungarian
0000001A
Icelandic
0000000F
Irish
00000023
Italian
00000003
Japanese
0000000B
Korean
00000017
Table 23-5: Languages as Defined in Apple’s Script.h File
Chapter 23 Localization
VISE X User’s Guide
Languages as Defined in Apple’s Script.h File
23–31
For This Language…
Use This Number:
Lappish
0000001D
Lapponian
0000001D
Latvian
0000001C
Lettish
0000001C
Lithuanian
00000018
Maltese
00000010
Norwegian
00000009
Persian
0000001F
Polish
00000019
Portuguese
00000008
Russian
00000020
Spanish
00000006
Swedish
00000005
Thai
00000016
Turkish
00000011
Urdu
00000014
Table 23-5: Languages as Defined in Apple’s Script.h File
User Defined Languages There may be times when the pre-defined languages do not offer enough specificity for a
given installer. For example, your installer may need to be differentiated for International
English, British, and Canadian content. For those cases, up to 10 languages can be defined
by the developer.
To create a user defined language for VISE X:
1. From the VISE X Languages folder, duplicate the language installer file which is
closest in content to the new language you wish to define. For our example we
would duplicate English Installer.
2. Rename the duplicate. In our case, we renamed the duplicate to “British English.”
3. Open the duplicate file with a resource editor.
4. Edit whatever strings are necessary to be changed.
5. Edit the Insk resource.
Change the second bytes to be some unique number. A number in the 200 range is
preferable. In this example we used F1.
VISE X User’s Guide
Section 4 Advanced Features
23–32
Languages as Defined in Apple’s Script.h File
Change the 3rd byte from 0 to any number between 1 and 10.
Illustration 23-40: InsK Resource from Duplicated Language File
When VISE X is run, and when reading in the Insk resource, it will look at the 3rd
byte to see if it is a number between 1 and 10. If it is, then the name of that Language file will be listed alphabetically in the Language popmenu as in the example
below.
Illustration 23-41: Language popmenu displaying user defined
languages
Chapter 23 Localization
VISE X User’s Guide
Languages as Defined in Apple’s Script.h File
23–33
6. Assign items within the installer to the appropriate language.
7. When the installer is run, you can have an external code that will set the default
language to be one of the user defined languages. You will need to return a value
from the Xcod that is the item number of the language wanted in the popmenu.
VISE X User’s Guide
Section 4 Advanced Features
23–34
Chapter 23 Localization
Languages as Defined in Apple’s Script.h File
VISE X User’s Guide
24–1
Chapter 24
Scripting VISE X with AppleScript
Scripting VISE X and
Installers
There are three ways that AppleScript can be used in conjunction with VISE X:
1. As the creator of an installer, you may include AppleScript scripts within the
installer to perform various functions on the target system. Information about this
topic can be found below, in “Including AppleScript Scripts Within an Installer”
on page 24-1.
2. As the creator of an installer, you automate the process of building installers by
using AppleScript. Information about this topic can be found in this chapter, in
the section titled “VISE X and AppleScript” on page 24-3.
3. Customers who use your installer may use AppleScript scripts to control the installation process. For example, if your product will be installed by a network system
administrator, the administrator can automate the process by sending scripts controlling the process to the installer. For complete information about using AppleScript to control an installer application, see Chapter 25-Controlling an Installer
with AppleScript.
Including
AppleScript Scripts
Within an Installer
To include any AppleScript script in the installer:
1. Save your AppleScript script as an application.
2. Using a resource editor such as Resorcerer, open the script and copy the ‘scpt’
resource.
3. Create a new file (with the resource editor) and paste the ‘scpt’ resource into it.
4. Give the resource an available ID between 5000 and 9999 (inclusive) and save the
file as a standard resource file.
(For more information about the following steps, see Chapter 6-Assigning External Code.)
VISE X User’s Guide
Section 4 Advanced Features
24–2
Including AppleScript Scripts Within an Installer
5. Add the resource file to the installer via the Project window.
Illustration 24-1: Project window
6. Declare the resource in the installer. Be sure to use type ‘scpt’ and the ID assigned
in Step 4.
Illustration 24-2: Edit External Code dialog
7. Specify when the installer should call the resource (to execute the script).
Chapter 24 Scripting VISE X with AppleScript
VISE X User’s Guide
VISE X and AppleScript
VISE X and
AppleScript
24–3
This section contains information about the AppleScript commands that can be used with
VISE X.
The following actions within VISE X can be performed via AppleScript:
VISE X User’s Guide
■
“Opening an Archive” on page 24-4
■
“Saving an Archive” on page 24-4
■
“Closing an Archive” on page 24-4
■
“Bringing an Archive Up to Date” on page 24-5
■
“Setting the Validate Paths flag before Bringing an Archive Up To Date” on
page 24-5
■
“Setting the Assign Parent Package to New Files Flag” on page 24-5
■
“Extracting an Archive Item” on page 24-5
■
“Setting Billboard Mode” on page 24-6
■
“Setting the Current Build Target” on page 24-6
■
“Turning Build Directives On” on page 24-6
■
“Turning Build Directives Off” on page 24-7
■
“Turning Build Targets On” on page 24-7
■
“Turning Build Targets Off” on page 24-7
■
“Building an Install Set” on page 24-8
■
“Setting the value of an existing Variable” on page 24-8
■
“Editing an existing Download Site” on page 24-8
■
“Setting the Localization File” on page 24-9
■
“Exporting a Translator File” on page 24-9
■
“Importing a Translator File” on page 24-10
■
“Validating an Update File” on page 24-10
■
“Setting the Disk Sizes” on page 24-10
■
“Removing Compressed Data” on page 24-12
■
“Exporting VCT Data as XML” on page 24-12
■
“Creating a VCT from XML” on page 24-13
■
“Selecting an Archive Item” on page 24-14
■
“Setting Replace Options for the Selected Archive Item” on page 24-15
■
“Setting the Install Location for the Selected Archive Item” on page 24-16
■
“Deleting the Selected Archive Items” on page 24-17
■
“Creating an Updater Item” on page 24-17
■
“Opening the Updater Window for the Selected Updater Item” on page 24-18
■
“Setting the Source for the Open Updater Window” on page 24-19
■
“Setting the Target for the Open Updater Window” on page 24-19
Section 4 Advanced Features
24–4
VISE X and AppleScript
■
“Comparing Target and Source Files in the Open Updater Window” on
page 24-20
■
“Adding a File or Folder to the Archive” on page 24-20
■
“Creating an Empty Folder in the Archive” on page 24-21
The script examples shown here use the activate command to bring
VISE X to the frontmost process. In general, it is good practice to
activate a process before sending it Apple events.
Opening an Archive
To open an archive, use this script:
-- open an archive
tell application "VISE X"
activate
open {"full path name"} as alias
end tell
Full Path Name should always be constructed as in the example
below.
Saving an Archive
The following script is used to save the archive.
-- Save the archive
tell application "VISE X"
activate
SaveArchive
end tell
This script expects the archive to already be open.
Closing an Archive
To close the frontmost archive window, use this script:
-- close an archive
tell application "VISE X"
activate
CloseWindow
end tell
Chapter 24 Scripting VISE X with AppleScript
VISE X User’s Guide
VISE X and AppleScript
Bringing an Archive Up
to Date
24–5
The following script is used to update the frontmost archive using file paths stored for the
current build source.
-- Bring archive up to date
tell application "VISE X"
activate
BringUpToDate
end tell
This script expects the archive to already be open.
Setting the Validate
Paths flag before
Bringing an Archive
Up To Date
The following script is used to set the validate paths flag prior to bringing an archive up
to date.
-- Bring archive up to date
tell application "VISE X"
activate
BUTDValidatePaths "true"
BringUpToDate
end tell
If set to false and an item’s path is invalid, the item will be deleted when doing a Bring Up
To Date.
This script expects the archive to already be open.
Setting the Assign
Parent Package to New
Files Flag
This SetAssignPackagesFlag sets a global variable in VISE X which determines how to
default the Assign Parent Packages to New Files checkbox in the Bring Up To Date
window.
You can either pass a “true” or “false” to this AppleScript command.
The following script will set the Assign Parent Packages to New Files flag in VISE X to
true and then will perform a Bring up To Date.
tell application “VISE X”
activate
SetAssignPackagesFlag “true”
BringUpToDate
end tell
For more information on the function of the Assign Parent Packages to New Files
checkbox in the Bring Up To Date window, see the steps listed for “Bringing the Archive
Up To Date” on page 16-1.
Extracting an Archive
Item
VISE X User’s Guide
The ExtractItem AppleScript command will allow you to extract one item of the frontmost archive. The string that is passed is first, the full path name to the extract location
on the hard drive, then a "," then the full path name to item in the archive.
Section 4 Advanced Features
24–6
VISE X and AppleScript
To perform an update on one root level folder or file, use the following script example:
-- Extract archive item
tell application "VISE X"
activate
ExtractItem {"full path to extract location,full path to archive item"}
end tell
This script expects the archive to already be open.
Setting Billboard Mode
To set which billboard mode to use before building an installer use the SetBillboardMode
command. SetBillboardMode sets the current Billboard mode for the frontmost archive.
The billboard mode must be used with one of the following parameters:
■
Sequential
■
By Disk
■
By Package
-- setting billboard mode
tell application "VISE X"
activate
SetBillboardMode “Sequential”
end tell
Setting the Current
Build Target
The following script is used to set the current Build Target.
-- Set current Build Destination
tell application "VISE X"
activate
SetBuildTarget {"build target name"}
end tell
This script expects the archive to already be open.
Turning Build Directives The following script is used to turn on one Build Directive for the frontmost archive.
On
-- Turn a build directive on
tell application "VISE X"
activate
BuildDirectiveOn {"build directive name"}
end tell
When the BuildDirectiveOn command is used without a parameter, all Build Directives in
the frontmost archive will be turned on.
-- Turn all build directives on
tell application "VISE X"
activate
BuildDirectiveOn
Chapter 24 Scripting VISE X with AppleScript
VISE X User’s Guide
VISE X and AppleScript
24–7
end tell
These script expects the archive to already be open.
Turning Build Directives The following script is used to turn off one Build Directive for the frontmost archive.
Off
-- Turn a build directive off
tell application "VISE X"
activate
BuildDirectiveOff {"build directive name"}
end tell
When the BuildDirectiveOff command is used without a parameter, all build directives in
the frontmost archive will be turned off.
-- Turn all build directives off
tell application "VISE X"
activate
BuildDirectiveOff
end tell
These scripts expect the archive to already be open.
Turning Build Targets On The following script is used to turn on one build target for the frontmost archive.
-- Turn a build target on
tell application "VISE X"
activate
BuildTargetOn {"build target name"}
end tell
When the BuildTargetOn command is used without a parameter, all build targets in the
frontmost archive will be turned on.
-- Turn all build targets on
tell application "VISE X"
activate
BuildTargetOn
end tell
These scripts expect the archive to already be open.
Turning Build Targets
Off
The following script is used to turn off one build target for the frontmost archive.
-- Turn a build target off
tell application "VISE X"
activate
VISE X User’s Guide
Section 4 Advanced Features
24–8
VISE X and AppleScript
BuildTargetOff {"build target name"}
end tell
When the BuildTargetOff command is used without a parameter, all build targets in the
frontmost archive will be turned off.
-- Turn all build targets off
tell application "VISE X"
activate
BuildTargetOff
end tell
These scripts expect the archive to already be open.
Building an Install Set
The following script is used to build an install set using the active build destination.
-- Build install set
tell application "VISE X"
activate
Build
end tell
This script expects the archive to already be open.
Setting the value of an
existing Variable
The following script is used to set the value of an existing variable.
-- Set variable value
tell application "VISE X"
activate
SetVariable "VariableName,VariableValue"
end tell
This script expects the archive to already be open.
Editing an existing
Download Site
The following script is used to edit an existing download site of an archive. For more
information on web installers and download sites, see “Designating Download Sites” on
page 30-11.
-- Edit the archive’s first download site
tell application "VISE X"
activate
SetDownloadSite {"1,MyCompany West,ftp.westcoast.com, ¬
anonymous,user@westcoast.com,¬
FTP/webinstall/mac/VISEX,FTP"}
end tell
Chapter 24 Scripting VISE X with AppleScript
VISE X User’s Guide
VISE X and AppleScript
24–9
This script expects the archive to already be open and for the download site to already
exist.
Parameters:
■
Number of Download Site to edit
■
Site name
■
Server Address
■
User Name
■
Password
■
Initial Directory
■
Server Kind (FTP or HTTP)
Setting the Localization The following script is used to set the localization file of the archive. For more information on localization, see Chapter 23-Localization.
File
-- Set the archive’s language file
tell application "VISE X"
activate
SetLocalizationFile {"full path name of the localization file ¬
including the file name"}
end tell
This script expects the archive to already be open.
Exporting a Translator
File
The ExportTranslator command will allow you to export a translator file for localization
purposes. The items that you set here are similar to those that you choose in the Create
Translator dialog. For more information on localization, see Chapter 23-Localization.
Parameters for the ExportTranslator command are listed in the following script. See also
“Description of the ExportTranslator Parameters:” on page 24-10.
tell application “VISE X”
activate
ExportTranslator “FileName,SourceLanguageID,TargetLanguageID,¬
UseSourceLanguage”
end tell
The following script is used to export an English-to-French translator file that uses the
source language as the default translation.
tell application “VISE X”
activate
ExportTranslator “English to French,0,1,true”
end tell
These scripts expect the archive to already be open.
VISE X User’s Guide
Section 4 Advanced Features
24–10
VISE X and AppleScript
Description of the ExportTranslator Parameters:
1. file name - The first parameter is the name of the translator file. Be sure to use the
file extension .plist because VISE X will format the file as an Apple property list.
2. source language ID - The second item is the source language ID, which should
correspond to the language of the archive. The translator file created will contain
all items in the source language which need to be localized into the target language.
You can find language IDs in the system file script.h, which is installed with
Apple’s Developer Tools.
3. target language ID - The third item is the target language ID. You can find language IDs in the system file script.h, which is installed with Apple’s Developer
Tools.
4. use source language - The fourth item determines whether the target text lines in
the translator file should contain the source text. A “true” value places source text
in the target areas, and a “false” value leaves the target areas blank.
Importing a Translator
File
The following script is used to import a translator file for localization purposes. For more
information on localization, see Chapter 23-Localization.
tell application “VISE X”
activate
ImportTranslator {“Full path name of the import file”}
end tell
This script expects the archive to already be open.
Validating an Update
File
The following script is used to validate an update file within an archive.
-- Validate an update file
tell application “VISE X”
activate
ValidateUpdateFile {“Full path name of the update file ¬
including the file name”}
end tell
If no parameter is passed, all update files will be validated.
This script expects the archive to already be open.
Setting the Disk Sizes
The following script is used to set information about the sizes and names of the disks and
segments created by the installer. The items that you set here are similar to those that you
choose at the Edit Disk window. An explanation of the parameters of the SetDisk call
appears after the code.
-- Set the Disk Sizes and other disk information
tell application "VISE X"
activate
SetDisk “WhichDisk,DiskName,SegmentName,SegmentSize,DiskSize”
end tell
Chapter 24 Scripting VISE X with AppleScript
VISE X User’s Guide
VISE X and AppleScript
24–11
For example, to set the disk information for the first disk, naming the disk and segment
sizes sequentially, with a segment size of 620MB and a disk size of 650MB, the code would
be:
tell application "VISE X"
activate
SetDisk "1,Disk ^,Segment ^,620,650"
end tell
This script expects the archive to already be open.
Description of the SetDisk Parameters:
The following is a description of the parameters for the SetDisk call. These parameters
appear between double-quotation marks after the SetDisk statement, and are separated by
a comma, as shown in the sample script.
1. which disk - The first parameter is which disk to set. This corresponds to selecting
the disk to edit at the Installer Disk Names window. To enter information for the
first disk, type 1; for the second disk, type 2; etc. To set information for all disks,
type 0. To set the last disk in the set, type 255 (this ensures that the settings are
applied to the last disk in the set.)
■
disk number
■
0 = All Disks
■
255 = Last Disk
2. disk name - The second item is the name of the disk. This corresponds to the Disk
Name field in the Edit Disk window. If desired, you may leave this item blank;
however, you must include the correct number of commas. For example, to leave
the disk name blank, sample parameters would be "1,,Segment ^,620,650".
3. segment name - The third item is the name of the segment. This corresponds to
the Segment Name field in the Edit Disk window. If desired, you may leave this
item blank; however, you must include the correct number of commas. For example, to leave the segment name blank, sample parameters would be "1,Disk
^,,620,650".
4. segment size - The fourth item in this field corresponds to the Segment Size popmenu in the Edit Disk Menu. Type one of the following to specify the segment size
for the disk:
VISE X User’s Guide
■
1 = Fill Disk
■
value other than 1 indicates the custom segment size in megabytes
Section 4 Advanced Features
24–12
VISE X and AppleScript
5. disk size - The fifth item in this field corresponds to the Disk Size field in the Edit
Disk Window. Type the desired size of the disk in megabytes.
Illustration 24-3: SetDisk AppleScript example
Removing Compressed
Data
The following script is used to remove compressed data from VCTs, which is often done
to make the VCTs smaller for source control purposes.
-- Remove compressed data
tell application "VISE X"
activate
RemoveCompressedData
end tell
This script expects the archive to already be open.
Exporting VCT Data as
XML
You can use the ExportVCTasXML command to export VCT data as XML. For more
information on the export feature, see Chapter 31-Working With VCT Data as XML.
The following script exports the VCT to a bundle named “ArchiveExport.xvct” at the location “1:Development:VISE_X:” and deletes an existing bundle at that location if needed to
avoid a naming conflict. Be sure to note the comments that appear in the script directly
above the ExportVCTasXML command. These comments demonstrate all the possible
Chapter 24 Scripting VISE X with AppleScript
VISE X User’s Guide
VISE X and AppleScript
24–13
ways that you can use the command with or without its optional parameters. An explanation of the parameters of the command appears after the script example.
Illustration 24-4: ExportVCTasXML AppleScript example
This script expects the archive to already be open.
Description of the ExportXML Parameters:
1. bundle specification - The first parameter is the full path to the location VISE X
should use to export the bundle. This parameter is optional. If you call the ExportVCTasXML command with the first parameter left blank, VISE X will export the
data to the same location as the VCT, and name the bundle according to the rule
listed in the next item.
2. destination name - The second parameter is the name VISE X should use for the
bundle that it exports. This parameter is optional. If you leave this parameter
blank, VISE X will name the bundle “[VCT Name].xvct.”
3. delete existing - The third parameter determines whether VISE X should delete an
existing bundle that has the same name as the destination one. A “true” value
deletes an existing bundle, and a “false” value does not. (In the latter case, the command will return an error rather than delete an existing bundle.) This parameter is
optional. If you leave this parameter blank, the behavior is the same as if you had
set a “false” value. You can use this parameter to set the delete behavior even if you
left the first two parameters blank.
Creating a VCT from
XML
You can use the CreateVCTfromXML command to create a new VCT from XML that was
originally exported from another VCT. For more information on creating a VCT from
XML, see Chapter 31-Working With VCT Data as XML.
The following script accesses a bundle named “ArchiveExport.xvct” at the location
“1:Development:VISE_X:” and creates a new VCT with the data from the bundle. This
script saves the new VCT as “New.vct” at the location “1:Development:VISE_X:” and
deletes an existing VCT at that location if needed to avoid a naming conflict. Be sure to
note the comments that appear in the script directly above the CreateVCTfromXML command. These comments demonstrate all the possible ways that you can use the command
VISE X User’s Guide
Section 4 Advanced Features
24–14
VISE X and AppleScript
with or without its optional parameters. An explanation of the parameters of the command appears after the script example.
Illustration 24-5: CreateVCTfromXML AppleScript example
Description of the CreateVCTfromXML Parameters:
1. bundle specification - The first parameter is the path to the bundle that VISE X
should use to create the new VCT.
2. destination path - The second parameter is the full path to the location where
VISE X should create the new VCT. This parameter is optional. If you leave this
parameter blank, VISE X will create the VCT at the same location as the bundle
you specified in the first parameter, and name the VCT according to the rule listed
in the next item.
3. destination name - The third parameter is the name VISE X should use for the
VCT that it creates. This parameter is optional. If you leave this parameter blank,
VISE X will name the VCT “[Bundle Name].vct.”
4. delete existing - The fourth parameter determines whether VISE X should delete
an existing VCT that has the same name as the destination one. A “true” value
deletes an existing VCT, and a “false” value does not. (In the latter case, the command will return an error rather than delete an existing bundle.) This parameter is
optional. If you leave this parameter blank, the behavior is the same as if you had
set a “false” value. You can use this parameter to set the delete behavior even if you
left the second and third parameters blank.
Selecting an Archive
Item
You can use the SelectArchiveItem command to select an item in the archive window.
Once you’ve selected an item, you can use commands such as SetSelectedItemReplaceOptions and DeleteSelectedItems to perform actions on that item.
The following script demonstrates how to use the SelectArchiveItem command:
-- Select an archive item
tell application "VISE X"
activate
SelectArchiveItem {"full path to the archive item, or just the ¬
Chapter 24 Scripting VISE X with AppleScript
VISE X User’s Guide
VISE X and AppleScript
24–15
archive item name"}
end tell
Specifying the full path to the archive item can be useful when your archive includes more
than one item with the same name. If you specify just the name of the archive item when
you use this command, VISE X will select the first item in the archive that has that name.
This script expects the archive to already be open.
Setting Replace Options You can use the SetSelectedItemReplaceOptions command to set replace options for the
for the Selected Archive selected archive item.
Item
The SetSelectedItemReplaceOptions command does not apply to
action items, bundle updaters or updater items.
The following script demonstrates how to use the SetSelectedItemReplaceOptions command:
-- Set replace options for the selected archive item
tell application “VISE X”
activate
SetSelectedItemReplaceOptions with {replace option(s), with commas ¬
separating multiple options and “and” preceding the last option}
end tell
This script expects the archive to already be open.
You can use any of the following parameters with the SetSelectedItemReplaceOptions
command:
Replace Option
SetSelectedItemReplaceOptions
Parameters
If Newer
newer
If Newer or Equal
newerorequal
If Older or Equal
olderorequal
If Older
older
If Different
different
If Exists
exists
Compare Modification Dates
comparemodifieddate
Compare Creation Dates
comparecreatedate
Table 24-1: Parameters for SetSelectedItemReplaceOptions
VISE X User’s Guide
Section 4 Advanced Features
24–16
VISE X and AppleScript
Replace Option
SetSelectedItemReplaceOptions
Parameters
Compare Version
compareversion
Always
always
Never
never
Ask User
askuser
Ask If False
askiffalse
Rename Existing
renameexisting
Table 24-1: Parameters for SetSelectedItemReplaceOptions
The number of parameters that you need to pass for this command depends on the
replace options that you’re setting. For instance, setting the replace options to Always
would require just one parameter. Other options could require up to four parameters,
such as the following example:
-- Set replace options for the selected archive item
tell application “VISE X”
activate
SetSelectedItemReplaceOptions with newerorequal,compareversion,¬
askiffalse and renameexisting
end tell
This script expects the archive to already be open.
For more information on setting replace options, see “Replace Options” on page 5-50.
Setting the Install
Location for the
Selected Archive Item
The SetSelectedItemInstallLocation command allows you to set the location and domain
where the installer should install the selected archive item. You can also use this command
to set the location and domain for an action item’s search criteria.
The SetSelectedItemInstallLocation command does not apply to
bundle updaters or updater items.
The following script demonstrates how to use the SetSelectedItemInstallLocation command:
- Set an install location for the selected archive item
tell application “VISE X”
activate
SetSelectedItemInstallLocation {“install to location”} with {whichdomain}
end tell
Chapter 24 Scripting VISE X with AppleScript
VISE X User’s Guide
VISE X and AppleScript
24–17
For the first parameter, you can enter any install location that appears in VISE X’s Install
To popmenu. The possible values for the second parameter are systemdomain, localdomain, networkdomain, userdomain and classicdomain.
This script expects the archive to already be open.
For more information on setting install locations and domains, see the following areas of
this user’s guide:
Deleting the Selected
Archive Items
■
“Install To Location” on page 9-7
■
“Domain Location” on page 9-9
You can use the DeleteSelectedItems command to delete the selected archive item(s).
If the selected item is a folder or a bundle, the DeleteSelectedItems
command will delete the entire contents of the folder structure.
The following script demonstrates how to use the SetSelectedItemInstallLocation command:
- Delete the selected archive items
tell application “VISE X”
activate
DeleteSelectedItems
end tell
This script expects the archive to already be open.
Creating an Updater
Item
VISE X User’s Guide
You can use the CreateNewUpdater command to automatically do the following:
■
Create a single-file updater item in your archive. VISE X will create the updater
item directly below the item that is selected in the archive window. If nothing is
selected in the archive window, VISE X will create the updater item at the bottom
of the archive list.
■
Set one or more source files.
■
Set the target file.
■
Compare the source and target files.
■
Save the updater item.
■
Close the updater window.
Section 4 Advanced Features
24–18
VISE X and AppleScript
The following script gets three source files and a target file from the location “1:Development:” and creates a single-file updater named “myupdater”:
Illustration 24-6: CreateNewUpdater AppleScript example
This script expects the archive to already be open.
Description of the CreateNewUpdater Parameters:
1. updater name - The first parameter is the name that VISE X should use for the
updater item that it creates.
2. source file - The second parameter is the full path to each file that VISE X should
use as the source file(s).
3. target file - The third parameter is the full path to the file VISE X should use as
the target file.
For more information on building updaters, see Section 3-Building Updaters.
Opening the Updater
After you select a single-file updater item with the SelectArchiveItem command, you can
Window for the Selected open that item’s updater window with the OpenSelectedUpdaterItem command. You can
then use other commands to modify the updater item, as described below:
Updater Item
■
To set the target file, use SetUpdaterSourceSpec.
■
To set the source file, use SetUpdaterTargetSpec.
■
To compare the source and target files, which builds the updater item, use CompareFiles.
■
To close the updater window, use CloseWindow.
The following script demonstrates how to use the OpenSelectedUpdaterItem command:
- Open the selected updater item
tell application “VISE X”
activate
OpenSelectedUpdaterItem
end tell
Chapter 24 Scripting VISE X with AppleScript
VISE X User’s Guide
VISE X and AppleScript
24–19
This script expects the archive to already be open.
Setting the Source for
the Open Updater
Window
You can use the SetUpdaterSourceSpec command to set the source file(s) for the open
updater window.
The following script sets “sourceapp1,” “sourceapp2,” and “sourceapp3” as the source files
for the updater item “myupdater”:
Illustration 24-7: SetUpdaterSourceSpec AppleScript example
This script expects the archive and the updater window to already be open.
Description of the SetUpdaterSourceSpec Parameters:
1. updater name - The first parameter is the name of the updater item that has the
open updater window. This parameter is optional. If you leave this parameter blank,
VISE X will use the frontmost open updater window that it can find.
2. source file - The second parameter is the full path to each file that VISE X should
use as the source file(s).
Setting the Target for
the Open Updater
Window
VISE X User’s Guide
You can use the SetUpdaterTargetSpec command to set the target file for the open
updater window.
The following script sets “1:Development:targetapp” as the target file path for the updater
item “myupdater”:
Section 4 Advanced Features
24–20
VISE X and AppleScript
Illustration 24-8: SetUpdaterTargetSpec AppleScript example
This script expects the archive and the updater window to already be open.
Description of the SetUpdaterTargetSpec Parameters:
1. updater name - The first parameter is the name of the updater item that has the
open updater window. This parameter is optional. If you leave this parameter blank,
VISE X will use the frontmost open updater window that it can find.
2. target file - The second parameter is the full path to the file VISE X should use as
the target file.
Comparing Target and
To compare source and target files in the open updater window, which builds the updater
Source Files in the Open item, use this script:
Updater Window
-- Compare the source and target files, which builds the updater item
tell application “VISE X”
activate
CompareFiles “updater item name”
end tell
Specifying an updater item name when you use the CompareFiles command is optional. If
you do not include the name, VISE X will use the frontmost open updater window that it
can find.
This script expects the archive and the updater window to already be open.
Adding a File or Folder
to the Archive
To add a file or non-empty folder to the archive, you can use the AddObjectToArchive
command.
Chapter 24 Scripting VISE X with AppleScript
VISE X User’s Guide
VISE X and AppleScript
24–21
The following script gets a file from the location “1:Development:targetapp” and adds it
to the archive list. The new file will appear directly below the item that is selected in the
archive window, or if nothing is selected, it will appear at the bottom of the archive list.
Illustration 24-9: AddObjectToArchive AppleScript example
This script expects the archive to already be open.
To learn how you can use the AddObjectToArchive command to
add a file to an existing folder in your archive, see Illustration 24-10:
CreateNewFolderInArchive AppleScript example.
Creating an Empty
Folder in the Archive
To add an empty folder to the archive, you can use the CreateNewFolderInArchive command.
The following script creates an empty folder named “MyFolder” at the bottom of the
archive list (provided that no other archive items are selected at the time), and selects it.
Next, the script gets a file from the location “1:Development:targetapp” and adds it to the
newly created folder.
VISE X User’s Guide
Section 4 Advanced Features
24–22
VISE X and AppleScript
Illustration 24-10: CreateNewFolderInArchive AppleScript example
This script expects the archive to already be open.
Chapter 24 Scripting VISE X with AppleScript
VISE X User’s Guide
25–1
Chapter 25
Controlling an Installer with AppleScript
Installer applications created by VISE X can respond to a variety of AppleScript calls,
which are described in this section. For example, network system administrators might
wish to use AppleScript to control multiple installations of the software on all computers
on the network.
Although you might not use this information as a developer, you may wish to make the
following information available to your customers in case they wish to use AppleScript to
control the installation of your application.
The script examples shown here use the activate command to bring
the installer application to the frontmost process. In general, it is
good practice to activate a process before sending it Apple events.
Setting Easy Install
To set the installer to default to the Easy Install option, use this script:
-- Default to the Easy Install option
tell application "installer_name"
activate
SetInstall "Easy"
end tell
Setting Custom Install
To set the installer to default to the Custom Install option, use this script:
-- Default to the Custom Install option
tell application "installer_name"
activate
SetInstall "Custom"
end tell
VISE X User’s Guide
Section 4 Advanced Features
25–2
Selecting a Package
Installing the Software
To select a specific package in the installer, use this script:
-- Select a specific package
tell application "installer_name"
activate
Select "package_name"
end tell
Package Dependencies are ignored when using the Select and Deselect AppleScript commands to check and uncheck package checkboxes in a built installer.
For more information on Package Dependencies, see “Package
Dependencies” on page 4-3.
Deselecting a Package
To deselect a specific package in the installer, use this script:
-- Deselect a specific package
tell application "installer_name"
activate
Deselect "package_name"
end tell
Installing the
Software
To have the installer application install the software, use this script:
Updating the Drive List
To force the installer to rescan mounted disks to update the internal drive list, use this
script:
-- Run an installer
tell application "installer_name"
activate
DoInstall
end tell
-- Update the list of disk drives
tell application "installer_name"
activate
UpdateDriveList
end tell
Selecting the Install
Location
Selecting a Hard Drive
To select a specific hard drive as the installation location, use this script:
-- Select a specific hard drive as install location
tell application "installer_name"
activate
SelectDrive "hard_drive_name:"
Chapter 25 Controlling an Installer with AppleScript
VISE X User’s Guide
Selecting the Install Location
25–3
end tell
The colon after the name of the drive is crucial. For example, to
install the items to the drive named “Macintosh HD,” use SelectDrive "Macintosh HD:"
Selecting a Folder
To select a specific folder on a hard drive as the installation location, use this script:
-- Select a specific folder as install location
tell application "installer_name"
activate
SelectDrive "hard_drive_name:folder_name:"
end tell
The colon after the name of the drive is crucial. For example, to
install the items to the drive named “Macintosh HD” in the folder
named “Applications,” use SelectDrive "Macintosh HD:Applications:"
VISE X User’s Guide
Section 4 Advanced Features
25–4
Chapter 25 Controlling an Installer with AppleScript
Selecting the Install Location
VISE X User’s Guide
26–1
Chapter 26
Creating External Code
General External
Code Information
This chapter contains general information about creating external codes to use with VISE
X. An explanation of programming and debugging techniques for creating external code is
beyond the scope of this documentation. The procedure for attaching external code to an
installer is described in Chapter 6-Assigning External Code.
Types of Codes That Can VISE X extensively supports the addition of custom code to perform additional functions
required by your installer. This custom code can be in the following forms:
Be Used
When Codes Can Be
Called
VISE X User’s Guide
■
UNIX shell scripts saved as resource files of type ‘shsc’
■
AppleScripts saved as resource files of type ‘scpt’
■
CFPlugIns (file extension .bundle)
■
UNIX shell scripts saved as plain text files
External codes can be called at the following times:
■
When the installer checks the language of the operating system
■
When the installer is initialized
■
During event processing (main event loop)
■
When installation begins
■
After installation
■
Before a file is installed
■
After a file is installed
■
Before an Action Item is executed
■
Before an Action Item’s action is performed (after search criteria is executed)
■
After an Action item’s action is performed
■
When checking install sizes
■
When user selects a custom package
Section 4 Advanced Features
26–2
General External Code Information
Resource IDs and
Reference Constants
Resource ID numbers must be between 5000 and 9999, inclusive.
Using More Than One
Code
If more than one external code is assigned to an item, the codes will be called in the order
in which they are listed in the External Code List dialog box. In this case, be sure to
declare your codes in the proper order.
Nonexistent or
Misidentified Code
You may not build an installer that includes a call to nonexistent or misidentified external
code. If you attempt to build an installer under these circumstances, you will be alerted
about the problem, and creation of the installer will be aborted. Creating a diagnostic
report before building an installer will identify misidentified or nonexistent code, as well
as other problems that may affect the installer.
Automatically Copying
Items to Installer
Resources
The VISE X builder application includes a folder named “VISE X Extras,” which you can
find at the following location: VISE X.app/Contents/Resources/VISE X Extras. Anything
that you place in this folder will be copied to the bundle “Resources” folder of your
installers when they are built. You can then access the items using external code. An
advantage of automatically copying extra items to the installers is that you don’t have to
manually add the items to each installer after building it.
About the Samples
Folder
VISE X includes several sample projects that can build each of the possible external codes.
If you need to install these projects, run the VISE X installer and do a custom install for
“Samples.” Then see a folder called “Installer External Code.”
If desired, you may assign a unique 32-bit number, or RefCon (reference constant), to each
external code instance so that the location it was called from may be identified. This may
be helpful if you are using one external code to perform multiple tasks.
Illustration 26-1: Samples folder
The Samples folder contains numerous files that can help you create external code for use
with VISE X. This folder includes:
■
Chapter 26 Creating External Code
Header files for interfacing your external code with VISE X
VISE X User’s Guide
Creating External Code for VISE X Installers
26–3
■
Sample projects and external code
■
Resource templates that enable Resorcerer to correctly display VISE X file
resources
Be sure to look at the header files and sample code, as well as the extensive comments.
This is the fastest way to learn about the functions you can perform with external code
and VISE X.
Where to Find More
Information
For information on using UNIX shell scripts with VISE X installers, see “Executing UNIX
Scripts From the Installer” on page 26-21. For AppleScript information, see Chapter
24-Scripting VISE X with AppleScript. Information that is specific to CFPlugIns begins
below.
Creating External
Code for VISE X
Installers
To enable the move to universal binary installers, MindVision has transitioned VISE X to
the Xcode environment. As a result, external code that you call from your installers (other
than AppleScripts and UNIX shell scripts) must be in the form of CFPlugIns. Information
on how to create this type of external code for VISE X installers follows.
External Code
Guidelines
Here are some guidelines for creating your code:
■
You can start by copying one of our samples, and using it as a template.
■
The code must be compiled as a CFPlugIn.
■
You should use Xcode 2.2 or later to compile the code.
If you created external code resources for use with VISE X versions
prior to 3.0, you will need to convert those resources to universal
binaries, in the form of CFPlugIns. See “Converting External Code
Resources to CFPlugIns” on page 26-19 for more information on
that process.
External Code Details
Your external code should have a main entry point as follows:
static void XCodMain(ExternParmBlock *eInfo);
External codes are based around a paramBlock type interface:
struct ExternParmBlock {
short
version;
short
selector;
long
refCon;
long
flags;
Handle
userStorage;
short
easyCustom;
short
numberOfPackages;
VISE X User’s Guide
// current version of this ParmBlock
// where in the installer your external
code is being called from (see “ExternParmBlock->selector” on page 26-5)
// user defined number (number assigned
in VISE X External Codes dialog)
// bit flags (see “ExternParmBlock->flags” on
page 26-6)
// user storage handle - initialized to
nil at start of Installer
// only set & changeable when called
with kSelectorLaunchTime
// number of packages
Section 4 Advanced Features
26–4
Creating External Code for VISE X Installers
IPackageArrayHdl
packages;
Handle
easyInstallText;
ArcFileType
theFile;
EventRecord
theEvent;
DialogPtr
short
short
theDialog;
itemHit;
installFork;
ArcListHdl
fileList;
long
short
numberOfFiles;
movedItemsVRefNum;
long
short
movedItemsDirID;
logRefNum;
Handle
removeText;
Ptr
callBackProcs;
long
long
long
languageCode;
regionCode;
extraStorage1;
long
extraStorage2;
long
extraStorage3;
long
extraStorage4;
Str27
FSSpec
userPassword;
installerFSSpec;
// user entered password
// FSSpec of this Installer
SerialNumberList
serialList;
DownloadItemList
downloadList;
// Handle to array of serial numbers and
registration names (eSellerate use only;
deprecated in VISE X 3.0 and later)
// Handle to array of items downloaded
from a purchase (eSellerate use only;
deprecated in VISE X 3.0 and later)
Ptr
sublaunchData;
long
sublaunchDataSize;
Chapter 26 Creating External Code
// package handle (see InstallerDefines.h)
// handle to easy install text (displayed on the install window (easy
install only))
// information about the file to be
installed
// event record - used during event loop
call
// Install Dialog
// itemHit - Event loop processing
// which fork(s) of file to install (see
“ExternParmBlock->installFork” on page 26-14).
Initialized to kInstallFile
// Handle to a list of files that are in
the archive
// number of files in the ArcListHdl
// vRefNum of the moved items folder 0 =
not created
// dirID of the moved items folder
// refnum of the Installer log file 0 =
not open
// Handle to text to display if you
include an Uninstall
// array of callback routines used for
log file, debug window, and variable
manipulation
// current language code
// current region code
// For Developer use. Initialize to 0 at
// start of installer.
// For Developer use. Initialize to 0 at
// start of installer.
// For Developer use. Initialize to 0 at
// start of installer.
// For Developer use. Initialize to 0 at
// start of installer.
// Pointer to data to be passed to sublaunched installer
// Size of sub-launch data pointer
VISE X User’s Guide
Creating External Code for VISE X Installers
long
26–5
percentDone;
// Percentage complete (taken from progress bar)
// Number of files remaining to install
long
filesRemaining;
};
typedef struct ExternParmBlock ExternParmBlock, *ExternParmBlockPtr;
typedef pascal void (*XCodProcCallPtr)(ExternParmBlock *eInfo);
#if TARGET_CPU_PPC
enum {
uppXCODProcInfo = kPascalStackBased
| STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(ExternParmBlock *)))
};
ProcInfoType __procinfo = uppXCODProcInfo;
#endif
ExternParmBlock->version
#define kExternPBVersion
// Version number of the paramblock
// passed to the external routine,
// currently:
1000
ExternParmBlock->selector
From where in the Installer your external code is being called. This is useful if you have
one code with many different procedures; you'll need to know where this is being called:
#define kSelectorLaunchTime
0
#define kSelectorEvent
1
#define kSelectorBeforeInstall
2
#define kSelectorAfterInstall
3
#define kSelectorBeforeFile
4
#define kSelectorAfterFile
5
#define kSelectorCheckingSizes
6
#define kSelectorDynamicTime
7
#define kSelectorPackChanged
8
#define kSelectorPreAction
9
VISE X User’s Guide
// External Code being called at launch
time (install dialog is valid, but
invisible)
// External Code being called during
main event loop, ExternParmBlock.itemHit
will be filled in from DialogSelect
// External Code being called at the
beginning of the install routine
// External Code being called at the end
of install routine
// External Code being called Before a
file is to be installed
// External Code being called After a
file was installed
// External Code being called to calculate sizes - see “ExternParmBlock->flags” on
page 26-6 for if on Custom or Easy Install
// External Code being called to set the
localization language
// External Code being called when package checkbox changes state
// External Code being called after
doing the search but before the actual
action is taken - valid for Action Items
that do finds
Section 4 Advanced Features
26–6
Creating External Code for VISE X Installers
#define kSelectorInstallerQuit
10
#define kSelectorPostInitTime
11
// External Code being called when the
installer quits - Allows for Cleanup
// External Code being called at the end
of initialization
ExternParmBlock->refCon
The RefCon is a 32-bit number identified in the Edit Codes window in VISE X that identifies the location from which the code was called. This may be useful if you call one external code from different locations for more than one task.
ExternParmBlock->flags
These are bit flags that are set for your information or can be set by your external routine
(marked as Changeable).
#define kCancelInstall
(1L << 0)
#define kWhichInstall
(1L << 1)
#define kCreateMovedFolder
(1L << 2)
#define kRemoveInstall
(1L << 4)
//
//
//
//
//
//
//
//
//
//
//
//
//
Cancel Install bit
if (gPBExtern.flags & kCancelInstall)
then quit
install •Changeable•
Easy or Custom Install bit
if ((gPBExtern.flags & kWhichInstall)
== 0) then doing Easy Install else
it’s custom install
Set this flag to tell the Installer
to create the Moved Files Folder in
the System Folder
If this flag is set, the user has
selected Uninstall
ExternParmBlock->userStorage
This handle is initialized to nil at the start of the installer. You can use this to create and
store anything that you want. It is passed to all external code unmodified until the
installer is quit.
ExternParmBlock->easyCustom
This number is only used at time of initialization. Its default is what was selected in the
Setup Installer dialog from VISE X. You can change the default install to one of the following two constants.
#define kGotoEasyInstall
#define kGotoCustomInstall
1
2
// default to Easy Install
// default to Custom install
ExternParmBlock->numberOfPackages
This is the number of packages that are defined (including the Easy Install Package).
ExternParmBlock->packages
This is a handle to an array of package definitions
struct IPackageType {
Str63
Str255
Str9
Chapter 26 Creating External Code
ipk_Name;
ipk_Description;
ipk_Version;
//
//
//
//
Internal Structure for packages
Package Name
Package Description
Package Version
VISE X User’s Guide
Creating External Code for VISE X Installers
short
unsigned short
long
long
unsigned char
ipk_IconID;
ipk_UniqueID;
ipk_Size;
ipk_BillBoardID;
ipk_NeedRestart;
unsigned char
unsigned char
unsigned char
ipk_Index;
ipk_Internal;
ipk_Checked;
26–7
// Package Icon ID#
// Unique ID Assigned to each package
// Package Size
// Internal Use
// Need Restart Flag 0 = No Restart, 1 =
Need Restart
// internal index
// Package Checkbox is on=true or
off=false
ipk_MEP;
// Mutual Exclusive Package
ipk_ListPackage;
// If this package is a List Package
ipk_ShowInPM;
// Show in popmenu with "Easy Install",
"Custom Install", etc.
ipk_DefaultPkgOn;
// If this package checkbox defaults to
on
ipk_MustSelectOne; // List Package Option
ipk_CanSelectMultiple;
// List Package Option
ipk_ExpandStatus;
// Whether or Not the Parent Package is
expanded
ipk_ListHelp;
// Handle to a PICT resource for the
List Package Help
ipk_ListHeader;
// A Pascal String for the List Package
Header Message
ipk_ListFooter;
// A Pascal String for the List Package
Footer Message
ipk_Gestalts[2];
// Bits for which Gestalts To Check
ipk_Indent;
// Indentation level of the package
ipk_Internal2;
// Internal Use
ipk_OnOnDep[kMaxPackFlags];
//Internal Use
ipk_OnOffDep[kMaxPackFlags];
//Internal Use
ipk_OffOnDep[kMaxPackFlags];
//Internal Use
ipk_OffOffDep[kMaxPackFlags];
//Internal Use
ipk_SKU;
// Internal Use
ipk_UserFlag;
// Developer Defined String[4]
ipk_PackExtraBytes; // Extra padding bytes for Disk Space
calculations
Boolean
Boolean
Boolean
Boolean
Boolean
Boolean
unsigned char
Handle
Str255
Str255
long
unsigned char
unsigned char
long
long
long
long
Str32
Str4
long
};
typedef struct IPackageType IPackageType;
typedef IPackageType *IPackageTypePtr;
IPackageType.ipk_Name
Name of the package
IPackageType.ipk_Description
Description of the package (seen in information dialog from the custom install)
IPackageType.ipk_Version
Version # of the package (seen in the information dialog from the custom install)
VISE X User’s Guide
Section 4 Advanced Features
26–8
Creating External Code for VISE X Installers
IPackageType.ipk_IconID
Package Icon (seen in the information dialog from the custom install)
IPackageType.ipk_UniqueID
Unique ID assigned to this package
IPackageType.ipk_Size
Package Size in bytes (sum of bytes of all files assigned to the package, seen in custom
install when user selects the info icon for a package)
IPackageType.ipk_Billboard
Internal use only
IPackageType.ipk_NeedRestart
0 = no restart, 1 - restart needed. If the package is installed, this defines whether or not to
restart the machine when the user quits the installer. If 1, then it also requires that all
other applications be quit before the installation can occur.
IPackageType.ipk_Index
Internal index.
IPackageType.ipk_Internal
Internal use only
IPackageType.ipk_Checked
True or false. Determines whether or not this package checked in the Custom Install.
IPackageType.ipk_MEP;
If this package is a Mutually Exclusive Package
IPackageType.ipk_ListPackage;
If this package is a list package
IPackageType.ipk_ShowInPM;
If this package will be displayed in the Easy Install popmenu
IPackageType.ipk_DefaultPkgOn;
If this package will be defaulted to checked
IPackageType.ipk_MustSelectOne;
List package option
IPackageType.ipk_CanSelectMultiple;
List package option
IPackageType.ipk_ExpandStatus;
Chapter 26 Creating External Code
VISE X User’s Guide
Creating External Code for VISE X Installers
26–9
Whether or not this parent package is expanded
IPackageType.ipk_ListHelp;
Handle to a PICT for the help for this List Package
IPackageType.ipk_ListHeader;
List Package header text (pascal string)
IPackageType.ipk_ListFooter;
List Package footer text (pascal string)
IPackageType.ipk_Gestalts;
Gestalts to check before this package is displayed in the custom install list, and shown in
the easy install text.
IPackageType.ipk_Indent;
Indentation level of the package. Maximum is 4.
IPackageType.ipk_Internal2;
Internal use only
IPackageType.ipk_OnOnDep[kMaxPackFlags]
Internal use only
IPackageType.ipk_OnOffDep[kMaxPackFlags]
Internal use only
IPackageType.ipk_OffOnDep[kMaxPackFlags]
Internal use only
IPackageType.ipk_ipk_OffOffDep[kMaxPackFlags]
Internal use only
IPackageType.ipk_SKU
Internal use only
IPackageType.ipk_UserFlag
Characters entered by the developer in the Edit Package dialog of VISE X. This can be
used to identify the package through external code. Maximum of four characters.
IPackageType.ipk_PackExtraBytes
Extra padding bytes entered by the developer in the Edit Package dialog of VISE X. When
calculating and displaying disk space needed for the package, the installer will add the pad
bytes to the total space requirement.
VISE X User’s Guide
Section 4 Advanced Features
26–10
Creating External Code for VISE X Installers
ExternParmBlock->easyInstallText
Handle to the text for the Easy Install window. (For example, "This installs the version of
the product and its associated data files.) The best time to change this handle is at launch
time, before the install dialog appears.
ExternParmBlock->theFile
This structure contains information about the last file manipulated (found, installed, etc.).
You can change fields in the file structure if you want (unless otherwise noted).
struct ArcFileType {
Str32
Str32
unsigned long
unsigned long
long
long
long
short
short
long
long
long
long
long
long
long
long
unsigned long
FInfo
long
long
long
Handle
unsigned long
unsigned long
unsigned long
short
unsigned short
unsigned short
unsigned short
unsigned long
Chapter 26 Creating External Code
af_Name;
af_Internal1;
af_CreateDate;
af_ModDate;
af_DirID;
af_Internal2;
af_Internal3;
af_Internal4;
af_vRefNum;
af_CompDataFork;
af_CompResFork;
af_unCompDataFork;
af_unCompResFork;
af_SegNumber;
af_Internal5;
af_Internal6;
af_Internal7;
af_CRC;
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
File Name
Internal Use Only
Modification Date of File
Modification Date of File
Directory ID
Internal Use Only
Internal Use Only
Internal Use Only
Volume Reference Number
Size of compressed data fork
Size of compressed resource fork
Size of uncompressed data fork
Size of uncompressed resource fork
Segment Number file is in
Internal Use Only
Internal Use Only
Internal Use Only
Checksum
af_FInfo;
af_Flags;
// FileInfo
// special location flags and replace
flags
af_ExtractFlags[2]; // gestalt calls bit flags (Gestalts to
call before installing this file)
af_Internal8;
// Internal Use Only
af_ActionName;
// Handle to name Action Item name
af_CodePreActionFlags;
// external code to call doing the
action of an Action Item - after the
search
af_CodeBeforeFlags; // external code to call before installing flags
af_CodeAfterFlags; // external code to call after installing flags
af_ActionSearchFlags;// Used for Action Items and Default
Install Location
af_UniqueID;
// a unique number used by the installer
af_MergeIntoID;
// UniqueID of file to merge into
af_InstallIfID;
// Install this file if Install Action
item/fails succeeds
af_Version;
// 4 bytes 1st part, 2nd & 3rd parts,
development stage, prerelease version
VISE X User’s Guide
Creating External Code for VISE X Installers
unsigned
unsigned
unsigned
unsigned
unsigned
char
char
char
char
char
26–11
af_InstallWhen;
af_Directory;
af_Internal9;
af_Internal10;
af_InstallDisk;
// Install if Succeeds or Fails
// File is a directory (if nonZero)
// Internal Use Only
// Internal Use Only
// disk the uncomp. file is supposed to
be on 0 = compressed
af_Locked;
// file - locked - from ioFlAttrib
af_LanguageBits[2]; // PopMenu Value for "Language" Country
Code (1...37)
af_RegionBits[2];
// PopMenu Value for "Region" Country
Code (1...62)
af_Internal11;
// Internal Use Only
af_PackageFlags[kMaxPackFlags];
// package flags
af_DirectiveFlags[kNumDirectiveLongs]; // Build directive
flags
af_PathID;
// Which folder is it in
af_FileGroup;
// File Group for Web Installer purposes
af_LongNameIndex;
// Internal Use Only
af_InstallToDomain; // FindFolder() Domain constant used for
OSX
af_UnixPrivBits;
// Internal UNIX flags; rwx rwx rwx &
symbolic link
af_UnixUserBits;
// Internal UNIX flags; set user to
wheel, root, etc.
af_Internal11;
// Internal Use Only
af_Internal12;
// Internal Use Only
af_VariableValue;
// Variable value for Set/Test Variable
unsigned char
unsigned long
unsigned long
unsigned char
long
long
unsigned long
unsigned char
long
unsigned char
long
long
long
short
Str255
};
typedef struct ArcFileType ArcFileType;
typedef ArcFileType *ArcFilePtr;
Fields can be changed unless otherwise noted.
ArcFileType af_Name
Name of file to be installed
ArcFileType.af_CreateDate
Creation date of file
ArcFileType.af_ModDate
Modification date of file
ArcFileType.af_DirID
Directory ID of the location where the file is going to be installed or was installed
VISE X User’s Guide
Section 4 Advanced Features
26–12
Creating External Code for VISE X Installers
ArcFileType.af_vRefNum
Volume reference number where the file is going to be installed or was installed
ArcFileType.af_CompDataFork
Compressed size of the data fork of the file •do not change•
ArcFileType.af_CompResFork
Compressed size of the resource fork of the file •do not change•
ArcFileType.af_unCompDataFork
Size of the uncompressed data fork of the file •do not change•
ArcFileType.af_unCompResFork
Size of the uncompressed resource fork of the file •do not change•
ArcFileType.af_SegNumber
Which segment the start of the file is in •do not change•
ArcFileType.af_CRC
Checksum of the file •do not change•
ArcFileType.af_FInfo
Finder info on the file
ArcFileType.af_Flags
Private
ArcFileType.af_ExtractFlags
Which gestalt calls get called before installing this file. Each bit in this field is associated
with the Gestalt menu in the Info window in VISE X. •do not change•
ArchFileType.af_ActionName
Handle to the name of the Action Item being called in the installer
ArcFileType.af_PackageFlags1,2,3
To which packages this file is assigned. Each bit in this field is associated with the Package
menu in the Info window in VISE X. •do not change•
ArcFileType.af_CodeBeforeFlags
Which external codes get called before installing this file. Each bit in this field is associated with the Before Installing code menu in the Info window in VISE X. •do not
change•
ArcFileType.af_CodeAfterFlags
Chapter 26 Creating External Code
VISE X User’s Guide
Creating External Code for VISE X Installers
26–13
Which external codes get called after installing this file. Each bit in this field is associated
with the After Installing code menu in the Info window in VISE X. •do not change•
ArcFileType.af_ActionSearchFlags
What Search Criteria (such as Name, Type or Creator) was selected for the current Action
Item or for the Default Install Location
ArcFileType.af_UniqueID;
This is a unique # assigned to this file from within VISE X when the file is added to the
archive. •do not change•
ArcFileType.af_MergeIntoID;
This is a unique ID # of another file to merge this file into
ArcFileType.af_InstallIfID;
This is a unique ID of a Find Action which says whether or not to install this file based on
the result of that Find action
ArcFileType.af_Version;
This is the 4 bytes from the vers resource of the file when it was added to the archive. (1st
part, 2nd & 3rd parts, development stage, prerelease version)
ArcFileType.af_InstallWhen;
This is when to install a file based on a Find Action. 0 = install when find was successful.
1 = install when find failed.
ArcFileType.af_Directory
This is a non zero value if this a directory •do not change•
ArcFileType.af_InstallDisk
Which disk contains this uncompressed file. A value of 0 means it is compressed in the
segment •do not change•
ArcFileType.af_Locked
If this file is to be locked or not after installing. A non-zero value means to lock the file
after installing.
ArcFileType.af_LanguageBits
Bit field that corresponds to which languages are selected for the file. Each bit in this field
is associated with the Languages menu in the Info window in VISE X. Legal values are 1-37.
ArcFileType.af_RegionBits
Bit field that corresponds to which regions are selected for the file. Each bit in this field is
associated with the Regions menu in the Info window in VISE X. Legal values are 1-62.
ArcFileType.af_PackageFlags
VISE X User’s Guide
Section 4 Advanced Features
26–14
Creating External Code for VISE X Installers
Bit field that corresponds to which packages are selected for the file. Each bit in this field
is associated with the Packages menu in the Info window in VISE X.
ArcFileType.af_DirectiveFlags
Bit field that corresponds to which build directives are selected for the file. Each bit in
this field is associated with the Build Directives menu in the Info window in VISE X.
ArcFileType.af_PathID
This is the unique ID of the parent folder of the file
ArcFileType.af_FileGroup
This is the File Group for the file. File Group is used for Web Installer purposes only.
ArcFileType.af_InstallToDomain
This is the Mac OS X domain to which the file will be installed.
ArcFileType.af_UnixPrivBits
Bit field that corresponds to which permissions (such as Owner-r and Other-w) are
selected for the file. Each bit in this field is associated with the Permissions menu in the
Info window in VISE X.
ArcFileType.af_UnixUserBits
Bit field that corresponds to which groups (such as Wheel and Root) are selected for the
file. Each bit in this field is associated with the Group menu in the Info window in
VISE X.
ArcFileType.af_VariableValue
This field stores the value of a VISE X variable (up to 255 characters) for use when the
ArcFileType is a Set Variable or Test Variable action item.
ExternParmBlock->theEvent
The current event from WaitNextEvent/GetNextEvent
ExternParmBlock->theDialog
The Installer Dialog
ExternParmBlock->itemHit
The itemHit returned from DialogSelect
ExternParmBlock->installFork
Which forks of the file to install. This field is defaulted to kInstallFile, and your external
routine would need to change it to one of the following if needed.
kDontInstallFile
Chapter 26 Creating External Code
0
// Don't install the file
VISE X User’s Guide
Creating External Code for VISE X Installers
kInstallDataFork
kInstallResFork
kInstallFile
ExternParmBlock->fileList
26–15
1
2
3
// Install Data Fork Only
// Install Resource Fork Only
// Install Both
This is a handle to a list of files to be installed. It is a handle of ArcFileTypes
ExternParmBlock->numberOfFiles
This is the number of files that are in the ExternParmBlock->fileList
ExternParmBlock->movedItemsVRefNum
This is the volume reference number of the volume containing the Moved Items folder.
When the Macintosh restarts, files placed in this folder will be deleted by the Installer
Cleanup Extension, and then the folder itself will be deleted. If movedItemsVRefNum ==
0 then folder has not been created.
ExternParmBlock->movedItemsDirID
This is the directory ID of the moved items folder. Make sure movedItemsVRefNum != 0
before trying to access this folder. Otherwise, the folder has not been created.
ExternParmBlock->logRefNum
This is the file reference number of the log file, so you can annotate the log file in any
way you want. If this logRefNum == 0 the file has not been opened/created yet.
ExternParmBlock->removeText
Handle to the text for the Install window when the user has chosen "Uninstall" from the
Easy Install/Custom Install/Uninstall popmenu. (For example, “This removes MyApp 2.0
and its associated data files.”) The best time to change this handle is at launch time, before
the install/uninstall dialog appears.
Using the following callback routines, external code can instruct the installer to perform
various tasks.
// CallBack Constants
#define kAddStrToLogFileCallBackId
0
#define kGetVariableCallBackId
1
#define kSetVariableCallBackId
2
#define kAddStrToDebugWindowCallBackId 3
#define kSetInternalsCallBackId
4
#define kCheckGestaltCallBackId
5
#define kCheck4WebUpdateCallBackId
6
#define kMyFindFolderCallBackId
7
#define kGetItemLongNameCallBackId
8
//
typedef void (*LogFileProcPtr)(Str255 theString, Boolean spaceAfter, Boolean addCR);
This routine writes a string to the log file.
typedef void (*GetVariableProcPtr)(Str255 variableName, Handle *theHandle);
VISE X User’s Guide
Section 4 Advanced Features
26–16
Creating External Code for VISE X Installers
This gets the value of a user-defined variable and returns a handle to that data. You will
need to use the handle size to set the string’s length.
typedef OSErr (*SetVariableProcPtr)(Str255 variableName, Str255 newValue);
This sets the value of a variable.
typedef void (*DebugWindowProcPtr)(Str255 theString, Boolean addCR);
This adds a string to the debug window.
typedef void (*SetInternalsProcPtr)(long mask, long values);
This routine sets internal installer variables to control whether any one of the following
actions occur: display Read Me, automatically start the installation process, allow multiple
installs or set the installer’s quit flag. For details, see “Setting VISE X Internal Variables”
on page 26-16.
typedef void (*CheckGestaltProcPtr)(long whichFile, Boolean *gestaltPassed);
This checks whether a given install file passes the gestalt checks assigned to it. The whichFile parameter for this routine is an index into the list of files to install (eInfo->fileList).
typedef void (*Check4WebUpdateProcPtr)(Boolean *updateAvailable);
For use with Active Web Installers only, this routine checks whether an update to the
installer is available.
typedef OSErr (*MyFindFolderProcPtr)(short vRefNum, OSType folderType,
Boolean createFolder, short *foundVRefNum, long *foundDirID);
This is VISE X’s internal FindFolder routine. You can use it to perform some checks that
are unavailable through Apple’s FindFolder routine.
typedef CFStringRef (*GetItemLongNameProcPtr)(ArcFilePtr theFile,
UInt32 *theEncoding);
This routine returns an install item’s long filename (if one exists) as a CFString, and also
returns the filename’s encoding (usually UTF-8). You can use this routine to access an
install item’s long filename before or after installing the item. For information on the use
of long filenames within VCTs, see “Changing an Item’s Long Name” on page 9-6 and
“Installing Items with UTF-8 Encoding” on page 23-4.)
For examples of how to call these routines, see the ExternCodeDefines.h file.
Setting VISE X Internal
Variables
The SetInternals callback routine allows external code to set various internal installer variables. For this, the external code must pass the following information to the routine:
■
A mask to specify which variable to set
■
A value to set for the variable
These are the actions that SetInternals can control:
Display Read Me
Setting Bit 0 on the mask tells the installer whether to display Read Me at startup.
mask = 0;
value = 0;
Chapter 26 Creating External Code
VISE X User’s Guide
Creating External Code for VISE X Installers
BitSet(&mask,0);
BitSet(&value,0);
BitClr(&value,0);
Start the Installation
Process
26–17
// Force the installer to not show Read Me at startup
// Allow installer to show Read Me at startup
Setting Bit 1 on the mask tells the installer whether to automatically start the installation
process.
mask = 1;
value = 1;
BitSet(&mask,1);
BitSet(&value,1);
BitClr(&value,1);
Allow Multiple Installs
// Force the installer to automatically start executing
// Force the installer to not automatically start executing
Setting Bit 2 on the mask tells the installer whether to allow multiple installs.
mask = 2;
value = 2;
BitSet(&mask,2);
BitSet(&value,2);
BitClr(&value,2);
Set Installer’s Quit Flag
// Force the installer to not allow multiple installs
// Force the installer to allow multiple installs
Setting Bit 3 on the mask sets the installer’s quit flag. (The installer won’t see this routine
until the main event loop.)
mask = 3;
value = 3;
BitSet(&mask,3);
BitSet(&value,3);
BitClr(&value,3);
// Set the done flag
// Clear the done flag
Helpful Hints
Checking
kSelectorCheckingSizes
When writing external codes that will be attached to a file and called Before Installing,
make sure that you test the selector against kSelectorCheckingSizes.This is necessary
because external codes attached to files and called Before Installing will also get called
when the installer needs to recalculate the space needed to install files.
Most of the time, however, you’d only want to do something when the external code is
called when the file is actually being installed. So, you want to get out of your external
code if selector is equal to kSelectorCheckingSizes.
Here’s a code snippet you can use:
static void XCodMain(ExternParmBlock *eInfo)
{
// Make sure this External Code was compiled with the current Headers
if (eInfo->version != kExternPBVersion) {
SysBeep(1);
goto exit;
}
// Make sure we are not called for checking sizes
VISE X User’s Guide
Section 4 Advanced Features
26–18
Creating External Code for VISE X Installers
if (eInfo->selector == kSelectorCheckingSizes) {
goto exit;
}
// ... YOUR CODE GOES HERE ...
exit:
return;
}
Marking Codes
Be sure to mark external code resources (and any additional resources that your code may
require, such as STR#, DLOG, and DITL) as preload and non-purgeable to prevent disk
swapping when loading and calling the code.
CFPlugIn Names for
Specialized Functions
The following CFPlugIn names are reserved for specialized functions:
■
PostInit.bundle
■
PackChangedXcod.bundle
■
DynamicXCod.bundle
If you add a CFPlugIn with one of these reserved names to your archive, the built installer
will perform the functions described here.
The process for adding these CFPlugIns is simplified compared to other types of custom
code. All you need to do is add the code to your archive via the PlugIns/Scripts section of
the Project window, and build your installer. You do not need to declare the codes to
make them available to the installer.
The Samples folder (see “About the Samples Folder” on page 26-2)
includes three sample Xcode projects that demonstrate use of the
specialized functions that follow. The names of the samples are Post
Initialization, Package Changed and Language Selector. You can copy
these projects and customize them for your own needs, if desired.
If you include a CFPlugIn named PostInit.bundle, the custom code will be called at the
end of initialization, just before the installer hits the main event loop.
If you include a CFPlugIn named PackChangedXcod.bundle, any time a package is
checked or unchecked by the user, this external code will get called, allowing you to perform some custom function. If you return a non-zero value in eInfo->itemHit, the list will
be redrawn and the size requirements will be recalculated.
A CFPlugIn named DynamicXCod.bundle will be called when the installer is first
launched. The value in eInfo->itemHit will equal what System language the user has
installed (English, French, etc.). The value in eInfo->region will contain what region the
user has installed. The external code can change the values of these two fields in the eInfo
paramblock. You may want to do this to display a list of languages the installer supports
and let the user choose which language of the product to install. The external code could
then fill in the proper language code and region code that applies to what the user chose.
Chapter 26 Creating External Code
VISE X User’s Guide
Sending Information to Sub-launched Installers
26–19
Checking for
Cancellations and Errors
To check whether the customer canceled the installation or if there was an error during
the install process, check (externParamBlock->flags & kCancelInstall). If the value is zero,
then the install was successful; if the value is non-zero, then the install was not successful.
Converting External
Code Resources to
CFPlugIns
To enable the move to universal binary installers, MindVision has transitioned VISE X to
the Xcode environment. As a result, external code that you call from your installers (other
than AppleScripts and UNIX shell scripts) must be in the form of CFPlugIns. VISE X
includes a sample Xcode project that you can use to convert your existing external code to
CFPlugIns. The default location for the project is: VISE X/Samples/Sample Projects/
Installer External Code/Generic External Code.
To convert legacy external code to CFPlugIns:
1. From the Finder, open the source file for the external code that you want to convert. Later, you can copy code from this file and paste it into the new source file.
2. Within the Generic External Code folder, double-click EC_PlugIn.xcodeproj to
open the Xcode project. (Xcode is required.)
3. Select the PlugIn.c source file for editing.
4. Replace code in PlugIn.c with your own as needed. You will probably need to make
your replacements within the code that begins with the comment “YOUR CUSTOM CODE STARTS HERE.” Do not modify the code that begins with the comment “OUR REQUIRED CODE STARTS HERE - PLEASE DO NOT MODIFY.”
5. Build the CFPlugIn. (All Xcode build settings should already be correct for the purposes of this project, including building as a universal binary.) The new CFPlugIn
will be located in the Output folder.
Sending Information
to Sub-launched
Installers
You can use external code to gather information such as user preferences and send the
information from a parent installer to a sub-launched installer.
(Information on how to create external code for VISE X installers appears earlier in this
chapter. For further reference, see “Sub-launch Action Options” on page 5-35 and Chapter 6-Assigning External Code.)
To send information from a parent installer to a sub-launched installer:
1. From the parent installer, use external code to do the following:
■
Collect the desired data.
■
Assign sublaunchData to point to the data to send.
■
Use sublaunchDataSize to specify the size of the data being sent.
(See “Creating External Code for VISE X Installers” on page 26-3 for specifics on
the required fields.)
2. Use a Sub-launch action item within the parent installer to sub-launch an installer.
3. From the sub-launched installer, use external code to read the data sent by the parent installer.
VISE X User’s Guide
Section 4 Advanced Features
26–20
Keeping a Debugger From Quitting
The Samples folder includes a sample project called “Sub-launch”
that demonstrates using external code to collect information and
send the information to a sub-launched installer. If you need to
install the samples, run the VISE X installer and select the “Samples”
Custom Install option.
Keeping a Debugger
From Quitting
When the archive setting Shutdown Applications Before Installing is on, any running
application, including a debugger, will be shut down before the installation. During
debugging of external code it may be necessary to override this archive setting.
To prevent certain applications from shutting down when using “Shutdown Applications
Before Installing,” a SdEx resource can be added to the Installer.
To add a SdEx reource to your installer using Resorcerer:
1. Place the MV Resorcerer Templates file in your Resorcerer Private Templates folder.
(The MV file contains a template so that you can edit the SdEx resource.)
2. Open your archive with Resorcerer.
3. In the archive, create a new Resource of Type SdEx with an id of 1000.
Illustration 26-2: Creating a SdEx Resource
4. In the new SdEx resource window click New.
Illustration 26-3: Adding a New SdEx Resource
Chapter 26 Creating External Code
VISE X User’s Guide
Executing UNIX Scripts From the Installer
26–21
5. Double-click on the word Type, enter the type code of the application you wish to
remain running, and click OK.
Illustration 26-4: Entering the Application Type
6. Double-click on the word Creator, enter the creator code of the application you
wish to remain running, and click OK.
Illustration 26-5: Entering the Application Creator
7. Close and save the VCT. When you build and run the Installer, the identified application will not quit.
You can add more applications to the exception list as long as they are all kept in the 1000
resource.
For information on the Shutdown Applications Before Installing setting, see “Designing
the Installer’s Behavior” on page 10-18.
Executing UNIX
Scripts From the
Installer
With its UNIX foundation, Mac OS X opens the door for many existing UNIX applications to transfer to the Macintosh platform. To capitalize on this opportunity, VISE X can
execute UNIX scripts from the installer.
There are two different ways to include a UNIX shell script in the installer:
■
Save the shell script in a plain text file and add the text file to the installer via
the Project window. See “Including Shell Scripts as Plain Text Files” on
page 26-22.
■
Save the shell script in a resource of type ‘shsc’ and add the resource file to the
installer via the Project window. See “Including Shell Scripts as Resource Files”
on page 26-23.
Also consider the UNIX Script action, which offers offers a simple
way to execute UNIX shell scripts from the installer. This action is a
good choice for when you don’t need to perform actions on
installed items. For access to standard UNIX parameters such as $1,
you’ll need to use the more advanced methods described here. See
“UNIX Script Options” on page 5-48.
VISE X User’s Guide
Section 4 Advanced Features
26–22
Executing UNIX Scripts From the Installer
VISE X includes several sample projects that demonstrate using shell
scripts with installers. If you need to install these projects, run the
VISE X installer and do a custom install for “Samples.” Then see a
folder called “Installer External Code.”
Including Shell Scripts
as Plain Text Files
To allow for shell script creation without a resource editor, VISE X supports adding shell
scripts to the Project window as plain text files.
To include a UNIX shell script in the installer:
1. Use a text editor to write the shell script.
2. Save the script as a plain text file.
(For more information about the following steps, see Chapter 6-Assigning External Code.)
3. Add the script file to the installer via the PlugIns/Scripts area of the Project window.
4. Declare the script in the installer.
5. Specify when the installer should call the script file (to execute the shell script).
When calling the script file, a VISE X installer will:
Information Passed From
Installers to Shell Scripts
■
Create a temporary file for this script on the target computer.
■
Execute the UNIX “system” command and pass the path to the temp file, which
will execute the shell script.
■
Pass install path and other information to the shell script, as noted below.
■
Delete the temp file.
An installer that calls the script file before or after installing a file will pass the following
information to the script:
■
Install path. This path (which contains file name, such as “/Library/Internet
Plug-Ins/MyFile”) may be accessed through the UNIX $1 parameter. If the path
to the file includes spaces (such as “/Library/Application Support”), you must
enclose the $1 parameter in quotes (“$1”).
■
File name. This value may be accessed through the UNIX $2 parameter.
■
Special VISE X variable. Before calling the ‘shsc’ resource, the installer will
need to declare a runtime variable called “ShellVar” (case must match) and set its
value. This value may be accessed through the UNIX $3 parameter. For information on declaring a variable, see Chapter 22-Using Runtime Variables. To learn
how to dynamically set the value of a runtime variable at install time, see “Set
Variable Options” on page 5-29.
■
RefCon value. This is the value entered in the RefCon field of the Edit External
Code dialog. It may be accessed through the UNIX $4 parameter. See “Declaring
External Code in an Installer” on page 6-3 and “Resource IDs and Reference
Constants” on page 26-2 for more information.
Chapter 26 Creating External Code
VISE X User’s Guide
Executing UNIX Scripts From the Installer
26–23
When an installer calls a script file before installing a nested folder,
the value accessible through the UNIX $1 parameter will be the
install path to the parent folder, rather than the nested folder. (This
is not an issue when the installer calls the script file after installing a
nested folder.) If you need to perform some action on a nested folder
before installing it, you can create a path to the folder by combining
the results of the $1 parameter (install path) and $2 parameter (folder name).
Information Passed From
Shell Scripts to Installers
The shell script can also return success or failure to the installer.
To set up the installer to cancel the installation if the shell script returns an error, use “exit
1” at the end of the script. This has the same effect as external code setting the kCancelInstall bit.
Scripts return a value of 0 for success and a non-zero value for failure.
Including Shell Scripts
as Resource Files
With this approach, the process for setting up your installer to execute UNIX scripts is
similar to the one used for including AppleScript scripts in an installer. In both cases, you
need to paste the script into a specific resource file type and set up the installer to recognize and call that resource.
To include a UNIX shell script in the installer:
1. Use a text editor to write the shell script.
2. Copy the script text.
3. Use a resource editor such as Resorcerer to paste the text into a resource of type
‘shsc.’
4. Give the resource an available ID between 5000 and 9999 (inclusive) and save the
file.
(For more information about the following steps, see Chapter 6-Assigning External Code.)
5. Add the resource file to the installer via the Resource Files area of the Project window.
6. Declare the resource in the installer. Be sure to use type ‘shsc’ and the ID assigned
in Step 4.
7. Specify when the installer should call the resource (to execute the shell script).
When calling the ‘shsc’ resource type, a VISE X installer will:
Information Passed From
Installers to Shell Scripts
■
Create a temporary file for this resource on the target computer.
■
Execute the UNIX “system” command and pass the path to the temp file, which
will execute the shell script.
■
Pass install path and other information to the shell script, as noted below.
■
Delete the temp file.
An installer that calls the ‘shsc’ resource before or after installing a file will pass the following information to the shell script:
■
VISE X User’s Guide
Install path. This path (which contains file name, such as “/Library/Internet
Plug-Ins/MyFile”) may be accessed through the UNIX $1 parameter. If the path
to the file includes spaces (such as “/Library/Application Support”), you must
Section 4 Advanced Features
26–24
Executing UNIX Scripts From the Installer
enclose the $1 parameter in quotes (“$1”).
■
File name. This value may be accessed through the UNIX $2 parameter.
■
Special VISE X variable. Before calling the ‘shsc’ resource, the installer will
need to declare a runtime variable called “ShellVar” (case must match) and set its
value. This value may be accessed through the UNIX $3 parameter. For information on declaring a variable, see Chapter 22-Using Runtime Variables. To learn
how to dynamically set the value of a runtime variable at install time, see “Set
Variable Options” on page 5-29.
■
RefCon value. This is the value entered in the RefCon field of the Edit External
Code dialog. It may be accessed through the UNIX $4 parameter. See “Declaring
External Code in an Installer” on page 6-3 and “Resource IDs and Reference
Constants” on page 26-2 for more information.
When an installer calls a script file before installing a nested folder,
the value accessible through the UNIX $1 parameter will be the
install path to the parent folder, rather than the nested folder. (This
is not an issue when the installer calls the script file after installing a
nested folder.) If you need to perform some action on a nested folder
before installing it, you can create a path to the folder by combining
the results of the $1 parameter (install path) and $2 parameter (folder name).
Information Passed From
Shell Scripts to Installers
The shell script can also return success or failure to the installer.
To set up the installer to cancel the installation if the shell script returns an error, use “exit
1” at the end of the script. This has the same effect as external code setting the kCancelInstall bit.
Scripts return a value of 0 for success and a non-zero value for failure.
Chapter 26 Creating External Code
VISE X User’s Guide
27–1
Chapter 27
VISE X Forms
VISE X Forms
Forms in VISE X are developer-defined dialogs which can be used for:
■
Displaying simple dialogs to convey information during the install
Illustration 27-1: Simple form
■
Displaying dialogs which query for information and set appropriate variables
Illustration 27-2: Form Used to Query for Information
VISE X User’s Guide
Section 4 Advanced Features
27–2
Sample Layout
Sample Layout
The illustration below contains a sample layout with at least one of each type item VISE X
forms can contain.
Illustration 27-3: Sample Form Layout
Creating a New Form
To create a new form:
1. Select Forms… from the Archive menu. The Form List is displayed.
2. Select New from the Form List window.
Illustration 27-4: Form List Window
Chapter 27 VISE X Forms
VISE X User’s Guide
Sample Layout
27–3
3. Enter a name for the Form in the Name field.
Illustration 27-5: Edit Form
4. Set the Language and/or Region(s) for the Form Layout.
A single form can be made up of multiple form layouts. Form layouts allow the
form to be localized. Before a form is displayed by a built installer, the language
and region of the user’s operating system are compared with the Language and
Region settings of a form’s layouts and the form layout with the best match will be
displayed.
When creating forms, it is important to finalize a base layout before working on
layouts for other languages and/or regions. Finalize the base layout, duplicate the
layout, localize the new layout, set the Language and/or Region settings for the
localized layout.
VISE X User’s Guide
Section 4 Advanced Features
27–4
Sample Layout
5. Select the Edit Layout button to edit the layout contents. A blank layout will be
displayed in the Form Layout Editor window and a new menu, Editor, will be
enabled.
Illustration 27-6: Form Layout Editor
The Editor menu contains all commands necessary to create, edit and test layout
content.
Illustration 27-7: Editor Menu
Chapter 27 VISE X Forms
VISE X User’s Guide
Configuring a Form Action to Display a Form
27–5
6. Set up the form layout contents using the Form Editor commands described below
(see “Form Editor Commands” on page 27-6).
Configuring a Form
Action to Display a
Form
Form Action items are used within an archive to determine form display. The display of a
form during an installation can be customized by:
■
The form action’s location in the Archive Window item list determines when the
form will be displayed during the install.
■
The form action’s Display Form If settings will determine if the form will be displayed during the install.
■
The form action’s package settings will determine which packages will display the
form during install.
To set up a form for display during an installation:
1. From the Archive Menu select New Action -> Form.
2. A Form Action will be added to the Archive Window Item List and the Form
Action window will open.
Illustration 27-8: Form Action
3. Name the Form Action.
4. Set up any Display Form If conditions. The Form Action, and therefore the form,
can be set to display conditionally according to:
VISE X User’s Guide
■
Build Directives - determine whether the form action will be included in
the current installer build.
■
Gestalt - determines whether the form action will be executed by the
installer based on a gestalt setting from the end user’s computer.
■
Language - determines whether the form action will be executed by the
installer based upon the language of the operating system upon which the
installer is run.
■
Region - determines whether the form action will be executed by the
installer based upon the region of the operating system upon which the
installer is run.
Section 4 Advanced Features
27–6
Form Editor Commands
If your form is designed with localized layouts and appropriate Language and/or Region settings, the Form Action’s Language and
Region settings need not be used. The form will display the correct
layout based on the language and/or region of the operating system
upon which the installer is run.
Use the Form Action’s Language and Region settings when a completely different form needs to be displayed based upon the language
and/or region of the operating system upon which the installer is run.
■
Action Result - determines whether the form action will be executed by the
installer based upon another action item’s success or failure (including Test
Variable actions) or upon the button selected in a Message action.
5. From the Display Form Options Form popmenu, select the form to be displayed.
6. Close and save the Form Action.
7. Make package assignments for the Form Action. The form will only be displayed
for packages which include the Form Action.
8. Determine when during the installation you wish the form to be displayed and drag
the Form Action up or down in the Archive Window to the desired location.
Form Editor
Commands
Using the Form Layout Editor is similar to setting up a dialog in a resource editor such as
Resorcerer.
Below is a description for each of the Form Editor commands:
Undo
When there has been a change, the Undo menu item will be enabled and will undo whatever was last changed. It does not undo any “new” items and does not undo a form layout
move or resize.
Select All
Select All will select all the items in your customized form layout.
Duplicate
When at least one item is selected, the Duplicate item will be enabled and will duplicate
the item(s). When an editable text, checkbox, radio group or radio button item is duplicated, it will ask for a new name for the new item. For the editable text item it will create
a new static text item with the new title. For the checkbox, radio button, or radio group
items it will change the title of the checkbox to the new name that you enter.
New Button
Select the New Button command. Then click in the Form Layout Editor window to create a new button item with a default title of “Button”. Rather than simply clicking, if you
Chapter 27 VISE X Forms
VISE X User’s Guide
Form Editor Commands
27–7
click and drag a new button will be created with bounds set by your click and drag. Upon
button creation a Button Item window will open allowing you to set button properties.
Illustration 27-9: Button Item Properties
Button
Property
Description
Title
Name which will be displayed on the button.
Default Button
Determines whether the button is drawn with dark outline to
indicate that it is a default button. At runtime, default buttons
can be selected from the keyboard by Return of Enter.
Top
The number of pixels between the top of the layout and the
top of the button.
Left
The number of pixels between the left side of the layout and
the left side of the button.
Height
The number of pixels from the top of the button to the
bottom. Default height is 18 pixels.
Width
The number of pixels from the left side of the button to the
right side of the button. Default width is 100 pixels.
Set
Allow selection of a variable to be set by the button. Clicking
the Set button opens the Variable List window from which an
existing variable can be selected or new variable can be created
and selected.
Table 27-1: Button Properties
VISE X User’s Guide
Section 4 Advanced Features
27–8
Form Editor Commands
Button
Property
Description
To
When this button is clicked by the user at installer runtime the
variable indicated in the Set field will be Set to the value
indicated in the To field.
Behavior
A button will have one of several behaviors based upon your
selection in this popmenu. For a description of each button
behavior see Table 27-2, “Button Behaviors,” on page 27-8.
Table 27-1: Button Properties
Buttons can be resized by changing Height and Width properties or by dragging a resize
handle on one of the button’s corners.
Button
Behavior
Description
Register
A button with behavior of Register will cause a dialog to be
displayed presenting the user with registration options. The
fields found on the form layout will be used for the
registration data. For more information on registration see
Chapter 28-On-Line Registration.
At runtime, if the user clicks a button which has its behavior
set to Register, other items in the form which are configured to
set variables will set their variables.
Continue
A button with behavior of Continue will cause the installation
to proceed.
At runtime, if the user clicks a button which has its behavior
set to Continue, other items in the form which are configured
to set variables will set their variables.
Cancel
A button with behavior of Cancel, when used in a Form
Action with a setting of Stop Install If User Cancels, will cause
the installation to be canceled.
At runtime, if the user clicks a button which has its behavior
set to Cancel, other items in the form which are configured to
set variables will not set variables.
Print Mailer
A button with behavior of Print Mailer will initiate the
printing of a registration mailer. The fields found on the form
layout will be used for the registration data. For more
information on registration see Chapter 28-On-Line
Registration.
At runtime, if the user clicks a button which has its behavior
set to Print Mailer, other items in the form which are
configured to set variables will set their variables.
Table 27-2: Button Behaviors
Chapter 27 VISE X Forms
VISE X User’s Guide
Form Editor Commands
27–9
Button
Behavior
Description
Print For Fax
A button with behavior of Print For Fax will initiate the
printing of a registration fax form. The fields found on the
form layout will be used for the registration data. For more
information on registration see Chapter 28-On-Line
Registration.
At runtime, if the user clicks a button which has its behavior
set to Print For Fax, other items in the form which are
configured to set variables will set their variables.
E-Mail
A button with behavior of E-Mail will initiate the sending of
an e-mail registration. The fields found on the form layout will
be used for the registration data. For more information on
registration see Chapter 28-On-Line Registration.
At runtime, if the user clicks a button which has its behavior
set to E-Mail, other items in the form which are configured to
set variables will set their variables.
Display Form
A button with behavior of Display Form will cause the display
of the form indicated by the behavior. Buttons with behaviors
of Display Form allow the creation of wizard-like interfaces for
your installer.
At runtime, if the user clicks a button which has its behavior
set to Display Form, other items in the form which are
configured to set variables will set their variables.
Table 27-2: Button Behaviors
When constructing forms, be sure to check the behavior of all buttons. The default behavior for a newly created button is Cancel. At
runtime, if the user clicks a button which has its behavior set to Cancel, other items in the form which are configured to set variables will
not set variables. If you do not set the button’s behavior to the
proper setting for your purposes you may end up with a form that
does not produce the desired results.
New Static Text
VISE X User’s Guide
Select the New Static Text command. Then click in the Form Layout Editor window to
create a new static text item. The default text is set to “Static Text”.
Section 4 Advanced Features
27–10
Form Editor Commands
Rather than simply clicking, if you click and drag a static text item will be created with
bounds set by your click and drag. Upon static text item creation a Static Text Item window will open allowing you to set static text properties.
Illustration 27-10: Static Text Item Properties
Besides setting the text, you can also set the font, font size, font style and color of the
static text item.
For Static Text items the initial default font is Application Font, Size
11, Style None. Any changes made to the Font, Size or Style popmenus become the defaults for new Static Text items created during
the current VISE X session.
Custom text colors that you set for a Static Text item will display in
black on Mac OS X versions earlier than version 10.2.
Chapter 27 VISE X Forms
VISE X User’s Guide
Form Editor Commands
New Edit Text…
27–11
Select the New Edit Text… command. Then click in the Form Layout Editor window to
create a new edit text item. Before the item is actually created, you must give the item a
“Field Name”.
Illustration 27-11: Naming a New Edit Text Item
Once the name has been entered a static text item will be created as a field label with the
text being the “Field Name” and a “:” appended to the end. To change the properties of
the Edit Text item, double-click on the edit text item or select the edit text item and hit
the Enter or Return key.
Illustration 27-12: Edit Text Item Properties
VISE X User’s Guide
Section 4 Advanced Features
27–12
Form Editor Commands
Edit Text Item
Property
Description
Name
Edit Text Item name. For internal purposes only. Can be
accessed and changed by selecting the edit text field and
choosing Edit “Field Name”… from the Editor menu or by
Option double-clicking the edit text field.
Text
Default text to be displayed in the field when the form is
displayed at runtime. Variables can also be entered as default
text. Be sure to use the % symbol before and after the variable
name. For example, if the variable name was “vProductName”
enter “%vProductName%” in the text field.
Required Input
Text must be entered into this field before continuing.
NOTE: When designing your forms, you may want to
communicate to the user which fields are required.
Top
The number of pixels between the top of the layout and the
top of the text edit field.
Left
The number of pixels between the left side of the layout and
the left side of the text edit field.
Height
The number of pixels from the top of the text edit field to the
bottom.
Width
The number of pixels from the left side of the text edit field to
the right side of the edit text field.
Set
Allow selection of a variable to be set to the text entered into
the edit text field at installer runtime. Clicking the Set button
opens the Variable List window from which an existing variable
can be selected or new variable can be created and selected.
Invisible
When checked on, the edit text field will be invisible during
form tests and at installer runtime. Invisible text edit fields
cannot be accessed by a user at installer runtime but can
contain text set via runtime variables or set data that you enter.
Invisible fields are included on Print For Fax and E-mail
registrations.
Table 27-3: Edit Text Item Properties
Chapter 27 VISE X Forms
VISE X User’s Guide
Form Editor Commands
New Checkbox…
27–13
Select the New Checkbox command. Then click in the Form Layout Editor window to
create a new checkbox. A new checkbox item needs to be named before it can be created.
Once the name has been entered the checkbox is created.
Illustration 27-13: Checkbox Item Properties
At creation, the checkbox Name and the checkbox Title are the same. To change the title
of the checkbox independent of the name of the field, select the checkbox and choose
Get Info… from the Editor menu. You can also Option double-click the checkbox field
to change the Field Name.
Checkbox
Property
Description
Name
Checkbox Item name. Can be accessed and changed by
selecting the checkbox item and choosing Edit “Field
Name”… from the Editor or by Option double-clicking the
checkbox item.
Title
The text to be displayed to the right of the checkbox at
installer runtime.
Default On
Determines whether the checkbox is checked on when the
form is initially displayed at installer runtime.
Top
The number of pixels between the top of the layout and the
top of the checkbox.
Left
The number of pixels between the left side of the layout and
the left side of the checkbox.
Height
The number of pixels from the top of the checkbox to the
bottom.
Table 27-4: Checkbox Properties
VISE X User’s Guide
Section 4 Advanced Features
27–14
Form Editor Commands
Checkbox
Property
Description
Width
The number of pixels from the left side of the checkbox to the
right side of the checkbox.
Set
Allow selection of a variable to be set by the checkbox.
Clicking the Set button opens the Variable List window from
which an existing variable can be selected or new variable can
be created and selected.
NOTE: When using checkboxes to set variables it is important
to know that when checked, the designated variable will be set
to 1 or 0.
Table 27-4: Checkbox Properties
New Radio Button
Selec the New Radio Button command. Then click in the Form Layout Editor window
to create a new radio button. You will be asked to name the radio button before its creation. Rather than simply clicking, if you click and drag, a new radio button will be created with bounds set by your click and drag.
To edit radio button properties double-click the radio button.
Illustration 27-14: Radio Button Item Properties
Radio Button
Property
Description
Title
The text to be displayed to the right of the radio button at
installer runtime.
Default On
Determines whether the radio button is on when the form is
initially displayed at installer runtime.
Top
The number of pixels between the top of the layout and the
top of the radio button.
Table 27-5: Button Properties
Chapter 27 VISE X Forms
VISE X User’s Guide
Form Editor Commands
27–15
Radio Button
Property
Description
Left
The number of pixels between the left side of the layout and
the left side of the radio button.
Height
The number of pixels from the top of the radio button to the
bottom.
Width
The number of pixels from the left side of the radio button to
the right side of the radio button.
Set
Allow selection of a variable to be set by the radio button.
Clicking the Set button opens the Variable List window from
which an existing variable can be selected or new variable can
be created and selected.
NOTE: When using a radio button not in a radio group to set
a variable it is important to know that the designated variable
will be set to 1 or 0.
Table 27-5: Button Properties
Radio buttons can be resized by changing Height and Width properties or by dragging a
resize handle on one of the button’s corners.
New Radio Group
Select the New Radio Group command. Then click in the Form Layout Editor window
to create a new radio group. You will be asked to name the radio group before its creation.
Rather than simply clicking, if you click and drag, a new radio group will be created with
bounds set by your click and drag.
A Radio Group (whether visible or invisible) causes all enclosed radio buttons to act as a
group - when one radio is selected the other radios are automatically deselected.
To edit radio group properties double-click the radio group item.
Illustration 27-15: Radio Group Item Properties
VISE X User’s Guide
Section 4 Advanced Features
27–16
Form Editor Commands
Radio Group
Property
Description
Name
Radio Group Item name. Can be accessed and changed by
selecting the edit text field and choosing Edit “Field
Name”… from the Editor or by Option double-clicking the
edit text field.
Is Visible
Determines whether the radio group is visible on the layout at
installer runtime.
Top
The number of pixels between the top of the layout and the
top of the radio group.
Left
The number of pixels between the left side of the layout and
the left side of the radio group.
Height
The number of pixels from the top of the radio group to the
bottom. Default height is 100.
Width
The number of pixels from the left side of the radio group to
the right side of the radio group. Default width is 100.
Set
Allow selection of a variable to be set by the radio group.
Clicking the Set button opens the Variable List window from
which an existing variable can be selected or new variable can
be created and selected.
NOTE: When using radio group to set variables it is important
to know that the designated variable will be set to the name of
the radio button which is on.
Table 27-6: Radio Group Properties
Radio Groups can be resized by changing Height and Width properties or be dragging a
resize handle on one of the group’s corners.
New Picture
Chapter 27 VISE X Forms
Select the New Picture command. Then click in the Form Layout Editor window to create a new picture. If there is a picture in the clipboard, a new picture item will be created
VISE X User’s Guide
Form Editor Commands
27–17
containing the picture that is in the clipboard. Rather than simply clicking, if you click
and drag a new picture item will be created with bounds set by your click and drag.
Illustration 27-16: Picture Item Properties
Picture
Property
Description
ResID
The PICT resource ID of the picture.
Top
The number of pixels between the top of the layout and the
top of the picture.
Left
The number of pixels between the left side of the layout and
the left side of the picture.
Height
The number of pixels from the top of the picture to the
bottom. Defaults to the actual height of the picture.
Width
The number of pixels from the left side of the picture to the
right side of the picture. Defaults to the actual width of the
picture.
Table 27-7: Picture Properties
Expand Right
When at least one item is selected, the Expand Right menu item will be enabled and will
increase the right boundary of the item(s) by 1 pixel. This will affect all selected items.
Reduce Right
When at least one item is selected, the Reduce Right menu item will be enabled and will
reduce the right boundary of the item(s) by 1 pixel.This will affect all selected items.
Get Info…
When at least one item is selected, the Get Info… menu item will be enabled and will display the items’ properties dialog.
Edit “Field Name”…
When at least one editable text, checkbox, radio button, or radio group item is selected
the Edit “Field Name”… menu item will be enabled and will display a dialog that allows
you to name the field.
VISE X User’s Guide
Section 4 Advanced Features
27–18
Item Order in Dialog
The field name will be used for:
■
Setting variable values in the case of radio buttons in a radio group
■
Submission via E-Mail
■
Output during Print for Fax
The name must be unique to the form that you are editing and is limited to 31 characters.
You can also edit the “Field Name” of any text, checkbox, radio button, or radio group by
holding down the option key while double clicking on it or typing Enter or Return. The
“Field Name” is also visible in the title bar of the dialog when doing a Get Info on an editable text of checkbox item, radio button or radio group.
Set Tab Order
The Set Tab Order command will enable you to set the tab order of the editable text
fields by clicking on the items in the new order. All fields must be set before the renumbering is done. You can get out of the tab ordering mode without reordering anything by
using either the escape key or command period. While in the tab ordering mode the cursor will change and no clicks will register unless they are within editable text items. Once
all editable text items have been selected, the reordering is set. You will still need to save
your changes in order to keep the order.
Save
The Save command is enabled when there has been a change to the form. Selecting this
item will save your changes without having to close the Form Editor.
Test…
The Test… command will display the customized dialog as your users will see it when they
install your software. You will be asked to save any changes before the dialog is displayed.
Be aware of the following issues when testing forms:
Close
Item Order in Dialog
■
If you have included buttons with any of the registration behaviors, you can test
the registration process.
■
The test operation does not do any manipulation of runtime variables.
■
The test operation uses the first registration destination in the list.
This will close the form layout dialog that you are editing. If you have made any changes
it will ask if you want to save them. You can also dismiss the form editor with the escape
key to bypass any of the saving process.
1. Buttons (Default button first)
2. Static Text
3. Edit Text (in tab order)
4. Checkboxes
5. Radio buttons
6. Pictures
7. Radio Groups
Chapter 27 VISE X Forms
VISE X User’s Guide
Keyboard Commands
27–19
Keyboard
Commands
Key
Behavior
Return or Enter
Performs Get Info on the selected item(s) which causes
the items properties dialog to be displayed.
Arrow keys
Move the selected items appropriately by 1 pixel.
Command-arrow keys
Move the selection 10 pixels.
Option-arrow keys
Move the selection 50 pixels.
Escape
Dismisses the dialog without saving your latest
changes. Exits the new item. Exits tab order mode.
Delete key
Deletes the selected item(s)
Table 27-8: Form Editor Keyboard Shortcuts
Importing and
Exporting Forms
Once you create a form in VISE X, you can export the form to make it available for use in
multiple archives. Exported forms retain all layouts and language and region settings of
the original forms.
To export a form:
1. Select Forms… from the Archive menu. The Form List is displayed.
2. Make sure the form that you want to export is selected, and then click Export.
Illustration 27-17: Form List Window
VISE X User’s Guide
Section 4 Advanced Features
27–20
Importing and Exporting Forms
3. In the standard Save dialog that displays, rename the exported form with its original name (or any other) if desired, and then click Save.
Illustration 27-18: Saving an Exported Form
4. In the Form List window, click Done.
To import a form:
1. Select Forms… from the Archive menu. The Form List is displayed.
2. In the standard Find dialog that displays, locate and select the file that you want to
import.
3. Click Choose. The Form List displays the newly imported form with the name
“Imported Form.”
4. If you want to rename the imported form, click Edit, enter a new name and then
click Done.
5. In the Form List window, click Done.
Chapter 27 VISE X Forms
VISE X User’s Guide
28–1
Chapter 28
On-Line Registration
Using Online
Registration
You may need information from end users in order to identify and keep in contact with
them. With Online Registration you can provide your users with a convenient way of
sending that information. Users will be presented with a dialog that you customize using
Forms.
Illustration 28-1: Example On-line Registration Dialog
VISE X User’s Guide
Section 4 Advanced Features
28–2
Using Online Registration
Once they have entered the requested data they will be able to submit the information to
you by either e-mail, printing a mailer, or printing a list of the data to be either faxed or
mailed.
Illustration 28-2: Register by E-mail, Mailer or Fax
On-line Registration Setup Overview:
1. Create Registration Destination - Set up data identifying where you want the user to
send their information.
2. Create Form - Set up the layout of the desired user interaction dialog.
3. Enable Online Registration - Indicate that you wish to include Online Registration
in the Installer by settings in Installer Settings or by using a Form Action.
Create Registration
Destination
Before you can use Online Registration you need to identify the addresses of where to
send the user's information.
To create a Registration Destination:
1. Select Registration Destinations… from the Archive menu. The Registration Destination List will be displayed
2. Click the New button to create a new registration destination.
Illustration 28-3: Creating a New Registration Destination
Chapter 28 On-Line Registration
VISE X User’s Guide
Using Online Registration
28–3
3. Enter your destination information into the appropriate fields.
Illustration 28-4: Edit Registration Destination Window
Field
Description
Name
The name of the destination. For example you might name one
destination “US Dest” and another “Non-US Dest”. This field is
for internal use only and will not be displayed in the built
installer.
Region(s)
The region setting determines when this particular destination
will be used based upon a comparison with the region setting of
the operating system upon which the built installer is run.When
the installer is run, it first looks for an exact region match. If
there is not a region match then the first destination set to Any
Match will be used.
Mail To
The address to which registration mailers will be mailed from the
region(s) checked. Enter all address components (i.e. name, street,
and city state zip). This information will be printed in uppercase
on the mailer.
BRM Permit No,
City & State
The Business Reply Mail Permit number followed by the city and
state which issued the BRM number. If the BRM field is left
blank then a Courtesy Reply Mail (CRM) mailer is created
instead.
Zip Code For
Bar Code
A Zip Code is only needed in this field if a BRM is being used. A
zip code entered here must be in Zip+4 format.
Table 28-1: Registration Destination Field Description
VISE X User’s Guide
Section 4 Advanced Features
28–4
Creating a Registration Form
Field
Description
Email Address
Enter the To address for the e-mail messages that the installer will
send to submit the registration data.
Reply Address
The value of the Reply Address field is used as the From address
of registration e-mail messages, and any undeliverable mail will be
bounced to this address.
Subject
The contents of the subject field will be used as the subject for
registration e-mail messages, enabling different e-mail subjects for
different products or e-mail destinations.
Table 28-1: Registration Destination Field Description
You may include more than one destination for the user's information. Which destination
to be used is determined by the region that is obtained from the user's computer. For
example if you had offices in the United States and France, you could set up a Registration Destination that would send all information to the France location if the user is
located in any of the European regions. Then you would set up another destination so
that information being sent from any other region would go to the U.S. location.
The mailers that can be printed are either a Courtesy Reply Mail or a Business Reply Mail
picture that is built into VISE X. In order to have the user able to print out a Business
Reply Mail mailer using our picture you must enter the BRM Permit Number, City and
State in the field provided. You must also include the 9-digit ZIP code that matches the
ZIP code included in the Mail To field.
When the user that is registering has chosen to e-mail their information, the installer will
send the data to the address in the Email Address field. The value of the Reply Address
field is used as the From address, and any undeliverable mail will be bounced to this
address. We recommend using a reply address that will also be returned to you but may go
through a different domain.
Creating a
Registration Form
A Form specifies the dialog box presented to the user to obtain registration input. A Form
is made up of a collection of Form Layouts which can be used to localize the form.
For example, you may create one “Registration” form that is made up of three layouts:
English, French, and Japanese. You can also specify a layout that is to be used regardless of
the user's language and region (this is the default).
Create Form
To create a form for on-line registration:
1. Select Forms… from the Archive menu. The Form List will be displayed.
2. Click the New button to create a new form.
Chapter 28 On-Line Registration
VISE X User’s Guide
Creating a Registration Form
28–5
3. The Edit Form dialog will be displayed.
Illustration 28-5: Edit Form dialog
4. Type a name for the form in the name field.
5. Set the Language and Region(s) for the selected layout.
Each form layout can have only one language setting but may have multiple region
settings.
6. Edit the first layout of the form by clicking the Edit Layout button. A blank form
layout is displayed in the Form Layout Editor window.
Illustration 28-6: New Form Layout
7. Add user interface elements such as Static Text, Editable Text, Checkboxes, and
Radio Buttons to your registration form. You can also use variable substitution, and
set variables from Forms. For complete information on constructing forms see
Chapter 27-VISE X Forms.
VISE X User’s Guide
Section 4 Advanced Features
28–6
Creating a Registration Form
8. In order for the form to function as a registration form it must contain a button
with a behavior of Register, Print Mailer, Print For Fax or E-Mail.
Illustration 28-7: Button with Register Behavior
The behaviors Print Mailer, Print For Fax and E-Mail perform only one function.
The Register behavior allows a choice to be made from Print Mailer, Print For Fax
and E-Mail when the button is clicked during installation. When a button with
behavior set to Register is clicked during installation, the following dialog will be
displayed allowing the user to pick the registration method.
Illustration 28-8: Registration Method Dialog
For samples of each of the registration methods see:
■
Illustration 28-14: E-mail Registration Sample
■
Illustration 28-15: Print Mailer Registration Sample
■
Illustration 28-16: Print For Fax Registration Sample
9. Define any invisible fields you may want. Invisible fields are displayed on Print For
Fax and in e-mail registrations. Invisible fields may be useful for items like Product
Name and Destination fax number.
Chapter 28 On-Line Registration
VISE X User’s Guide
Creating a Registration Form
28–7
10. Set the tab order for user input by selecting Set Tab Order from the Editor menu.
Illustration 28-9: Setting Form Tab Order
Click on the fields in the order of desired entry. When the form enters tab ordering
mode, each field will display a number indicating its current tab order. As you click
on a field, it will display the original tab order number followed by the new tab
order number. For example, 2 -> 1 indicates that the field was originally set to be
number two in the tab order but will now be set to be number one in the tab
order. When you have clicked on all fields the form will return to field edit mode.
Tab order is important for smoothing the flow of data entry Tab order can also be
important for invisible fields as tab order determines the order in which fields are
displayed in e-mail registrations and print for fax registrations.
To stop the process of setting tab order without saving any tab order changes, type
Command-period at any point before setting the tab order for the last field.
11. Test your form by selecting Test… from the Editor menu.
12. During test mode you will be able to test button behaviors and to see how items
will be displayed. Note that runtime variable substitution does not occur during a
form test
13. When your form test is complete, type Command-W to close the form layout test.
The following illustration is an example of a finished registration form. Note the use of a
variable to default field values. Print for Fax and Email registrations will print all fields on
VISE X User’s Guide
Section 4 Advanced Features
28–8
Creating a Registration Form
a form, even invisible forms. This form uses an invisible field which is filled in by variables
(%Product% %Version%) so that the product name and version number will print on the
mailer but will not be displayed in the form during installation. The form also has two
fields (Company and Serial #) which contain variables set by Xcod.
Illustration 28-10: Finished Registration Form
14. When you have finished your form layout type Command-W to close the Form
Layout Editor and return to the Edit Form dialog
To add localized layouts to the form:
15. If you need your registration form to display differently based upon Language and/
or Region you will need to set up localized layouts for your form. Start by setting
the Language and Region for your base layout. This should be the layout that has
been completely designed and tested.
16. Duplicate the completed layout and change the Language and/or Region settings
for the layout.
17. Edit the new layout for the language/region chosen.
Chapter 28 On-Line Registration
VISE X User’s Guide
Include Online Registration
28–9
Include Online
Registration
There are two ways to include online registration in your built installer. The first involves
settings in Installer Settings. The second involves use of a Form Action.
Including Registration
by Installer Settings
To include online registration in your built installer through Installer Settings:
1. From the Archive Menu select Installer Settings….
2. In Installer Settings select the Extras tab.
3. Check Include Online Registration Module.
Illustration 28-11: Include Online Registration via Installer Settings
4. Choose whether or not to add “Register Now…” to the File menu of your Installer
by selecting Add To File Menu.
5. From the Display Registration popmenu choose when you want the registration
form to be displayed.
Display Registration
Option
Description
At Launch Time
The registration form will be displayed when the
installer is first launched.
Before Installing
The registration form will be displayed after the
user clicks install but before files are installed
After Installing
The registration form will be displayed when the
install has been completed
Table 28-2: Display Registration Options
6. From the Registration Form choose which form to use as the registration form.
VISE X User’s Guide
Section 4 Advanced Features
28–10
Including Registration
by Form Action
Include Online Registration
You can choose to display your registration form by using a Form Action Item rather than
by using the options in Installer Settings.
Registering via Form Actions:
■
Allows the registration form to be displayed during the install process rather
than before or after
■
Allows the registration process to be conditional based upon execute if options
in the Form Action or by package assignment
To set up registration using a Form Action:
1. From the Archive Menu select New Action -> Form.
2. A Form Action will be added to the Archive Window Item List and the Form
Action window will open.
Illustration 28-12: Form Action
3. Name the Form Action.
4. Set up any Display Form If conditions. The Form Action, and therefore the registration form, can be set to display conditionally according to:
Chapter 28 On-Line Registration
■
Build Directives - determine whether the form action will be included in the
current installer build.
■
Gestalt - determines whether the form action will be executed by the
installer based on a gestalt setting from the end user’s computer.
■
Language - determines whether the form action will be executed by the
installer based upon a the language of the operating system upon which the
installer is run.
■
Region - determines whether the form action will be executed by the
installer based upon a the region of the operating system upon which the
installer is run.
VISE X User’s Guide
Include Online Registration
28–11
If the registration form is designed with localized layouts and appropriate Language and/or Region settings, the Form Action’s Language
and Region settings should not be used. The form will display the
correct layout based upon the language and/or region of the operating system upon which the installer is run.
Use the Form Action’s Language and Region settings when a completely different form needs to be displayed based upon the language
and/or region of the operating system upon which the installer is run.
■
Action Result - determines whether the form action will be executed by the
installer based upon another action item’s success or failure (including Test
Variable actions) or upon the button selected in a Message action.
5. From the Display Form Options Form popmenu select the form to be used for
registration.
6. Close and save the Form Action.
7. Make package assignments for the Form Action. The registration form will only be
displayed for packages which include the Form Action.
8. Determine when during the installation you wish the registration form to be displayed and drag the Form Action up or down in the Archive Window to the
desired location.
Illustration 28-13: Registration Form Arrangement
In the preceding example, the registration form is set to display immediately before
the application is installed. The packages settings indicate that the registration form
will only be displayed for packages which install the application.
VISE X User’s Guide
Section 4 Advanced Features
28–12
Registration Output
Samples
Registration Output Samples
Online registration can be set to send the user’s registrations by:
■
E-mail
■
Mailer
■
Print For Fax
■
The user’s choice of the above options
E-mail Registration Sample
Illustration 28-14: E-mail Registration Sample
Print Mailer Registration Sample
• If you have purchased Multimedia Voyager Pro, filling out this form ensures you are
notified of any updates, bug fixes, and news about our products.
• If you have not purchased our products, go ahead and fill out the registration form. We will
use it to notify you by email of new versions of our software. We will not use the information
to call, or otherwise hassle you about our products. If you later decide to purchase our
products, we will already have your information in our database.
N a m e : Paul Welsh
Job
Title: Product Communications
Company: MindVision Software
A d d r e s s 1 : 5901 N. 58th Street
Address2:
C i t y : Lincoln
S t a t e : NE
Zip: 68507-3249
C o u n t r y : USA
Phone: (402) 323-6600
F a x : (402) 323-6611
E M a i l : paul@mindvision.com
Serial
#: XXXX000000000
(Leave blank if you have not purchased).
please fold here
PLACE
STAMP
HERE
PRODUCT REGISTRATION
SCREAMIN' EAGLE SOFTWARE
5901 NORTH 58TH
LINCOLN NE 68507-3249
please fold here
Tape on bottom edge
Illustration 28-15: Print Mailer Registration Sample
The top portion of the mailer will contain an image of your completed registration
form. The mailer address in the center portion is dynamically written based upon
Chapter 28 On-Line Registration
VISE X User’s Guide
Custom Mailers
28–13
the Registration Destination region(s) setting.
Print for Fax Registration Sample
Please fax to Screamin' Eagle: (402) 323-6611
Registration information for: Multimedia Voyager Pro
Name: Paul Welsh
Title: Product Communications
Company: MindVision Software
Address1: 5901 N. 58th Street
Address2:
City: Lincoln
State: NE
Zip: 68507-3249
Country: USA
Phone: (402) 323-6600
Fax: (402) 323-6611
EMail: paul@mindvision.com
Serial #: XXXX00000000000
Illustration 28-16: Print For Fax Registration Sample
Custom Mailers
You can create your own mailer graphic by first starting with a copy of the standard mailers to ensure alignment and then modifying whatever is necessary. You can find the standard mailers in the Base Installer file in the VISE X Extensions folder. That folder is
located within the builder’s application bundle at: VISE X.app/Contents/Resources/VISE
X Extensions.
Your pictures will need to include the Mail To information and any other Permit Number
information. After completing the picture, paste it into the VCT file using a resource editor and assign it an ID within the range of 5000-10000. Within the destination dialog leave
the Mail To field blank and put the ID of your picture in the ZIP Code For Bar Code
field.
VISE X User’s Guide
Section 4 Advanced Features
28–14
Chapter 28 On-Line Registration
Custom Mailers
VISE X User’s Guide
29–1
Chapter 29
Install Locations
Install Locations
When VISE X is launched, the contents of the “Install To” and “Search Location” popmenus are dynamically built from location definition files found in the VISE X Locations
folder. The location of this folder within the VISE X application bundle is as follows:
VISE X.app/Contents/Resources/VISE X Locations. Extending the Install Locations is as
simple as adding one or more location definition files to the VISE X Locations folder.
Illustration 29-1: Standard VISE X Locations Files
Standard Install
Locations
VISE X ships with six location definition files in the VISE X Locations folder: System
Domain, Local Domain, Network Domain, User Domain, Classic Domain and xCustom
Location. The five files with “domain” in their names determine the install locations made
available when their respective domains are selected in the Domain popmenu. For example, if System is selected in the Domain popmenu, the contents of the “Install To” and
“Search Location” popmenus will be determined by the System Domain file. The xCustom Location file makes the following install locations available, regardless of the domain
selected in the Domain popmenu: Installer Bundle Location and Installer Location.
VISE X User’s Guide
Section 4 Advanced Features
29–2
Install Locations
Illustration 29-2: Install To and Domain Popmenus
Illustration 29-3: Search Location and Domain Popmenus
Additional Install
Locations
The six standard location definition files include the most commonly used install locations. Less commonly used install locations are not included in order to keep the “Install
To” and “Search Location” popmenus to reasonable lengths.
Should you need access to install locations not included in the standard location definition files, additional location definition files are available. These additional files — which
can be found in the VISE X Additional Locations folder — are: System Domain Extended,
Local Domain Extended, Network Domain Extended and User Domain Extended.
To extend the install locations available for the User domain, for instance, you would quit
VISE X and then add the User Domain Extended file to the VISE X Locations folder. The
next time you launched VISE X, the additional User domain install locations would be
available in the “Install To” and “Search Location“ popmenus.
Illustration 29-4: Adding User Domain Extended to VISE X Locations
Chapter 29 Install Locations
VISE X User’s Guide
Install Locations
29–3
The following illustration shows the additional install locations that will be available when
you add specific files to the VISE X Locations folder:
■
The first column from the left shows the additional locations made available by
the System Domain Extended file.
■
Column two shows the locations in the Local Domain Extended file.
■
Column three shows the locations in the Network Domain Extended file.
■
Column four shows the locations in the User Domain Extended file.
System ... Extended
VISE X User’s Guide
Local ... Extended
Network ... Extended
User ... Extended
Section 4 Advanced Features
29–4
Setting Install Locations With Variables
Some locations do not exist under older Mac OS versions. If you
plan to use a location that is not supported on an OS version your
customers may be using, you should create a gestalt check to ensure
that these locations exist, or deselect the Stop Install if “<type of
action>” Fails item at the top of the Action Item window.
Setting Install
Locations With
Variables
You can use a special VISE X runtime variable to dynamically set install locations at the
time of install.
VISE X makes the variable “InstallVar” available as an install location that can be selected
directly from the “Install To” and “Search Location” popmenus. At install time, installers
will substitute the current value of InstallVar whenever an item uses the variable install
location.
To set install locations with variables:
1. Open an existing archive or create a new one.
2. Define the variable InstallVar (use matching case) and set an initial value if desired.
For more information, see Chapter 22-Using Runtime Variables.
3. Add the required files, folders, bundles and action items to the archive.
4. For each action item that should use the value of InstallVar as a search location,
select Variable “InstallVar” from the “Search Location” popmenu. See Chapter
5-Creating Action Items for details.
5. For each install item that should use the value of InstallVar as an install location,
select Variable “InstallVar” from the “Install To” popmenu. See Chapter 9-Setting File and Folder Options for details.
6. In your install logic, set a value for InstallVar before executing an archive item that
will use the variable. You may set the value as many times as needed. Options for
setting the value of InstallVar include a Find action (see “Find Options” on
page 5-18) and a Set Variable action (see “Set Variable Options” on page 5-29).
To function as an install location, the InstallVar variable must contain a colon-separated full path (which is what a Find action will
return). Do not use a POSIX-based (slash-separated) path to set the
value of InstallVar.
Chapter 29 Install Locations
VISE X User’s Guide
30–1
Chapter 30
Active Web Installers
Active Web Installers
Your users will greatly benefit from technical breakthroughs that seamlessly address data
transfer rate, interrupted connections, and various hardware configurations for a convenient, trouble-free download and installation over the Web. End users frequently do not
need all the files contained in an installer. Previously, on-line users faced an often-daunting
task of either downloading complete installers or choosing just the right installer for their
system. MindVision’s Active Web Installer technology simplifies the user experience by
first downloading a small installer which can retrieve just the pieces needed for the user’s
specific requirements.
Users will benefit from reduced download times, reduced risk of download glitches, and
the most up-to-date software available. Developers will benefit from reduced server loads,
as well as an increase in customer satisfaction with the downloading and installation experience. In addition, MindVision’s technology provides developers with unprecedented flexibility in choosing when to offer updates and enhancements to on-line users. The Active
Web Install technology automatically handles interrupted connections and corrupted files.
When a connection is interrupted, previously downloaded files will remain intact on the
end user’s system and the remains of the active file being downloaded at the time of the
interruption will automatically be removed. When the end user reconnects, the download
will continue with the interrupted file and finish downloading the remaining files.
MindVision’s Active Web Install features include:
Active Web Installer
Setup
VISE X User’s Guide
■
Grouping and packaging of files to create the smallest-possible data sets for
downloading
■
Storing the downloaded data into the installer application for future installs
■
Various settings to easily handle the creation of an Internet-ready installer for the
Web
An Active Web Installer differs from any other installer you might create in only a few
ways. In addition to the normal setup items such as package setup and assignment, action
item creation, splash screen and billboard creation, an Active Web installer needs information about the way that files will be stored, called File Groups, and where on the web the
installer can obtain file groups, called Download Sites.
Section 4 Advanced Features
30–2
Active Web Installer Setup
Active web installers require a web server which supports HTTP 1.0
or greater.
Overview
Overview of steps necessary to create an Active Web Installer:
■
Set Web Installer specific Installer Settings.
■
Create a Web Install Build Target.
■
Set up File Groups and assign files to file groups.
■
Set up Download Sites.
■
Build the installer.
■
Place the File Group files at the designated web sites.
In the following pages we will go into more detail on each step needed to create an Active
Web Installer.
Creating a Web Install
build target
Build Targets are a part of VISE X’s advanced project management features. Build Targets
allow the developer to set up one archive which will be used to produce multiple installers. It is not uncommon to need a Web Installer, a CD installer and an Application Bundle installer produced from the same archive. Build Targets make setting up and building
multiple installers easy. For a full description of Build Targets, see Chapter 21-Advanced
Project Management. Installer Settings has a number of special options specifically for
Web Installers.
To create an Installer Setting for a Web Installer:
1. From the Archive menu select Installer Settings…
Chapter 30 Active Web Installers
VISE X User’s Guide
Active Web Installer Setup
30–3
2. Go to the Web tab of Installer Settings and check the options you would like for
your web installer.
Illustration 30-1: Installer Settings Web tab
See the table below for a description of each option.
Option
Description
Create Separate Catalog
When checked, a separate catalog file will be
created. This catalog enables the web installer
to self update when appropriate.
Strict Installer Data Time Stamp
Checking
When turned on, the built installer will require
the time stamp of the installer and the time
stamp of the VISEICat.idx file on the Web/
FTP server to be the same. This will require the
VISEICat.idx file to be uploaded to the Web/
FTP site every time you build.
Upload Cab File(s) To Web Server
At Build Time (FTP sites only)
When turned on, VISE X will upload CAB
files to the FTP servers listed in the Download
Sites dialog. (Do not use this feature if you
have HTTP servers listed in the Download
Sites dialog.) This feature requires the servers
to have FTP “STOR” command support.
Suppress Internet Dialup Dialog
Turning this checkbox on, prevents the
installer from displaying the “Please make sure
you have an active Internet connection” dialog
to the user. You may want to turn this on if
you are assured the user will already have an
active connection.
Table 30-1: Installer Settings Web tab Options
VISE X User’s Guide
Section 4 Advanced Features
30–4
Active Web Installer Setup
Option
Description
Allow User To Choose Download
Site
When turned on, a popmenu will appear in
the “Please make sure you have an active
Internet connection” dialog, allowing the user
to choose which site to download the data
from.
Suppress Internet Disconnect
Dialog
Turning this checkbox on, prevents the
installer from displaying the “Disconnect from
the Internet now” dialog to the user.
Byte Range Downloads
When turned on, VISE X will create a single
CAB file instead of using Group File
assignments. This feature allows for the
smallest and quickest downloads possible. It
also requires the web servers to be HTTP 1.1
compliant or have FTP “REST” command
support.
Table 30-1: Installer Settings Web tab Options
3. From the popmenu at the bottom left of the Installer Settings window, select Save
Settings As…
Illustration 30-2: Save Installer Settings
Chapter 30 Active Web Installers
VISE X User’s Guide
Active Web Installer Setup
30–5
4. Enter a name for the saved Installer Setting and click the Create button.
Illustration 30-3: Installer Setting Name
5. Close Installer Settings.
To create a Build Target for a Web Installer:
1. With an archive open, select Show Project Window from the Archive menu.
2. In the Project Window, click on the Targets heading.
Illustration 30-4: Project Window
3. Click the Add button at the top of the Project window to create a new build target.
The Build Target window is where you determine the type of installer you will be
building along with where that installer will be saved to and what, if any, post processing should occur.
VISE X User’s Guide
Section 4 Advanced Features
30–6
Active Web Installer Setup
4. In the Build Target window, type in a Name for the build target and select Web
Installer from the Format popmenu.
Illustration 30-5: Build Target set to Web Install
5. Clicking Create Debug will add the Debug Window to the Web Installer you
build. The Debug Window can be helpful when testing installers. You may want to
set up a build target for creating a debug web installer and another build target for
creating a non-debug or release installer.
6. From the Settings popmenu, select the Installer Settings set you created specifically
for your web installer. Whenever this target is built, it will use that Installer Settings
set.
Illustration 30-6: Selecting an Installer Setting for the Build Target
Chapter 30 Active Web Installers
VISE X User’s Guide
Active Web Installer Setup
30–7
7. Click Edit Path if you would like the Web Installer to be built to a location other
than the default.
8. Click OK to save your changes to the build target.
9. Click just left of the folder icon for the newly created build target to make it the
active build target. A bullet appears next to the My App Web Installer build target.
Uncheck the Default Target built target. Only checked build targets will be built
when the build command is executed.
Illustration 30-7: Project Window with new Web Installer Build Target
Duplicating a build target
There may be times when you want to duplicate a build target. For example, you could
duplicate a complex build target and make just one change to the copy so that it creates a
debug installer.
To duplicate a build target:
1. Click on the target name to highlight it.
2. Hold down the Option key and click Add.
Creating File Groups
After creating a web installer Build Target, you will need to create and assign files to File
Groups.
If you have checked Byte Range Downloads in the Installer Settings web tab File Group settings are ignored and only one CAB file
is built by the web installer. During the download portion of the
install, the installer pulls only the necessary items from the single
CAB file. Byte Range Downloads requires a web server which is
HTTP 1.1 compliant or which supports FTP “REST”.
To create a File Group:
1. From the Internet menu, select File Groups.
2. In the File Group List window click New.
VISE X User’s Guide
Section 4 Advanced Features
30–8
Active Web Installer Setup
3. In the Edit Group Name window, type in a group name and a file name for the
group file.
Illustration 30-8: Edit File Group Name
When the installer is built, file group files will also be created for placing on a web
server. Group names should be descriptive to both the developer and the end user
as the group name is used when assigning files to a group and is visible when file
groups are being downloaded at install time.
It is important to segment installers into file groups so that end users will be able
to download only the files necessary to complete the install options they have chosen.
When naming your file groups, you should consider the restrictions
of the web server where the file group files will reside. For example:
• Does the server allow filenames containing spaces or slashes?
• Will the server serve files that do not have extensions? If extensions are required, which ones does the server allow?
Also, note that VISE X uses the “.xdf” extension for VISEData.xdf, the single cab file
that it creates for web installers that use byte-range downloads.
Chapter 30 Active Web Installers
VISE X User’s Guide
Active Web Installer Setup
30–9
4. After creating all file groups you will be using, click OK to dismiss the File Group
List.
Illustration 30-9: File Group List
Assigning files to File
Groups
Files and folders are assigned to file groups in the same way that any other installer properties are assigned.
To assign files and folders to file groups:
1. Add the File Group item to an Archive Window layout.
For more information on adding fields to the Archive Window detail see Chapter
20-Customizing the Archive Window.
VISE X User’s Guide
Section 4 Advanced Features
30–10
Active Web Installer Setup
2. Select the item in the item list and select the desired File Group from the Group
popmenu in the Archive Window detail.
Illustration 30-10: Assigning files to file groups
If a folder is selected, then all items within that folder will be assigned to the file
group.
If a folder is selected in the Archive Window and it is set to Individual File. all
files within that folder will be set to Individual File. When the web installer is built
the folder will be created with individual group files for every file in the folder.
When the installer is run by an end user, it will look for that folder on the web
server’s Initial Directory. The installer will then try downloading the file from that
directory.
If In Installer is checked for a file, that item’s compressed data will be included in
the installer file itself and will not be downloaded as part of a file group.
Chapter 30 Active Web Installers
VISE X User’s Guide
Active Web Installer Setup
30–11
3. File Groups can also be assigned from an item’s Get Info window.
Illustration 30-11: Setting File Group in an item’s Get Info window
The Group item in the Get Info window changes to Disk when the
current build target is not set to Web Installer.
Designating Download
Sites
Within VISE X, download sites are predetermined web addresses where the built web
installer can retrieve file groups. You may set up multiple download sites. When an end
user runs an installer, a download site will be selected at random unless Allow User to
Choose Download Site is checked in Installer Settings.
To set up Internet download sites:
1. From the Internet menu select Download Sites.
2. In the Internet Site List click the New button.
VISE X User’s Guide
Section 4 Advanced Features
30–12
Active Web Installer Setup
3. In the Edit Internet Site window enter a Name, a Server Address, and Initial Directory.
Illustration 30-12: Edit Download Site
In the example above, the server at address http://www.server.westcoast.com contains a directory named WestcoastSoftware that contains a sub-directory named
MyApp which contains the File Group files created when the installer was built.
HTTP and FTP Server Notes
4. Set the Server Kind.
■
When choosing FTP, a user name and password must be entered even if
“anonymous” is used for the user name and an e-mail address is used for the
password.
■
HTTP 1.1 servers and FTP servers can benefit by using byte range downloads (enabled from Installer Settings Web tab). Byte range downloads
enable VISE X to disregard the file group settings and produce one large cab
file for placement on the server. During the installation, the web installer
gets just the part it needs from within the cab file without needing to download an entire file group file. This feature requires the web servers to be
HTTP 1.1 compliant or have FTP “REST” command support. For more
information, see “Byte Range Downloads” on page 10-30.
When entering Server Address, do not preceed with “http://”. The
http protocol declaration will be added by the web installer prior to
searching for the server at the address specified in the Server Address
field.
5. After creating all download sites you will be using, click OK to dismiss the Internet
Sites List
Creating a Separate
Catalog
A catalog for a web installer contains a list of items to process during the install, including
files, action items, packages, etc. Every web installer has an internal catalog. You can also
create an external catalog to put on the web site with the file groups. When the installer is
run by the end user, the date/time stamp within the installer is compared to that stored in
the VISEICat.idx file on the server. If the date/time of the catalog on the server is newer
than the installer’s internal catalog, a new installer will be downloaded. This allows you to
Chapter 30 Active Web Installers
VISE X User’s Guide
Active Web Installer Setup
30–13
update your installer code, and subsequently, update your product so the latest version of
your software is available for download.
This feature is automatically enabled for active web installers that use a separate catalog to
store install information on the web server. When appropriate, VISE X will use this catalog
to create a new installer for downloading.
For an initial release installer, a separate web catalog is not necessary. If files have been
updated or modified, a separate catalog will be necessary for installers to access the new
data.
To create a separate catalog for a web installer:
1. Open Installer Settings from the Archive menu.
2. Select the Web tab in the Installer Settings window.
3. Check the Create Separate Catalog checkbox.
4. Build the installer. The following items will be created:
■
The installer application
■
File group files for every file group with files assigned to it
■
A VISEICat catalog containing the installer catalog
■
A VISEICat.idx containing the installer date/time stamp
5. Copy the catalog files and the file group files to the web server in the directory
indicated in the download site.
Illustration 30-13: File Group and Catalog files placed on web server
6. If there are multiple download sites, repeat step 5 for each site unless Upload Cab
File(s) To Web Server At Build Time (FTP sites only) is checked in Installer
Settings web tab in which case cab files will be automatically uploaded to the server
at installer built time.
Verify Files on Server
After you have built your web installer and have the cab file(s) in place on the server you
can have VISE X verify the files on the server.
To verify files on the server:
1. From the Internet menu select Verify Files on Server.
If VISE X succeeds in verifying the files on the server, a message similar to the fol-
VISE X User’s Guide
Section 4 Advanced Features
30–14
The User’s Initial Experience
lowing will display:
Illustration 30-14: Files Verified On Server
If VISE X encounters a problem with verification, a message similar to the following will display:
Illustration 30-15: Error Validating Files On Server
The User’s Initial
Experience
When your users use the web installer you’ve just delivered, they should have an install
experience very similar to that of an application bundle installer. The installer file application can be delivered on CD or downloaded from the web. When the end user doubleclicks the installer, they are presented with the usual installer items. Splash screen, packages, interface type, and Install Location options are the same as those presented from an
application bundle installer with the exception of a Continue button rather than an
Chapter 30 Active Web Installers
VISE X User’s Guide
The User’s Initial Experience
30–15
Install button. Clicking the Continue button takes the user to a download preparation
window.
Illustration 30-16: Active Installer Install Window
Before downloading files the user is instructed to initiate a connection to the Internet. By
checking the Use Proxy checkbox, the user can enter proxy server and port information.
Illustration 30-17: Preparation to Download Files
The installer first tries to locate the server and check for the existence of a catalog newer
than that within the installer.
VISE X User’s Guide
Section 4 Advanced Features
30–16
The User’s Initial Experience
In the illustration that follows, the installer found a newer catalog..
Illustration 30-18: Catalog check during Install
Following the catalog check, the installer immediately begins downloading the file groups
necessary to install the items indicated by the user’s package selection. Only the necessary
file groups are downloaded and incorporated into the installer.
Illustration 30-19: Downloading file groups within the Installer
Chapter 30 Active Web Installers
VISE X User’s Guide
The User’s Subsequent Experiences
30–17
When all necessary file groups have been downloaded, the user is told that they may disconnect from their Internet connection.
Illustration 30-20: Download complete message
If the user clicks Cancel, the active installer will quit. All items that were downloaded are
now incorporated into the active installer for future install sessions.
If the user clicks Continue, the installation will proceed as if it were an application bundle installer.
Illustration 30-21: Installation progress
The User’s
Subsequent
Experiences
VISE X User’s Guide
After a web installer downloads the necessary file groups, they are incorporated into the
installer and do not need to be downloaded again unless they have changed.
Section 4 Advanced Features
30–18
The User’s Subsequent Experiences
When the user to runs the web installer again with the same package selection, the following message will be displayed.
Illustration 30-22: Message-Installer has all necessary files
If the Install button is clicked the initial installation will be repeated. If the Update button is clicked, the user is asked to initiate an Internet connection.
The installer then checks the data on the web server. If the data in the user’s installer is
the same as that on the server the following message is displayed.
Illustration 30-23: No download necessary
If the catalog on the server indicates that the data in the user’s installer is older than that
on the server, a new installer is downloaded, and the user can continue with the updated
install.
Chapter 30 Active Web Installers
VISE X User’s Guide
31–1
Chapter 31
Working With VCT Data as XML
To allow comparing and modifying installer projects outside of VISE X, the program can
export VCT data as XML. The XML file is formatted as an Apple property list file (file
extension .plist), so it can be opened and edited using Apple’s Property List Editor (a utility included with Apple’s Developer Tools). Also, the file is plain unicode text, which can
be edited using any text editor.
Some benefits of the exported .plist file are:
Exporting VCT Data
as XML
■
Source control. The .plist file is a textual representation of all the items in the
VCT. To find the differences between VCT versions, you can export each VCT as
XML and then use the tools of your choice to compare the .plist files.
■
Portability. Making changes to the .plist file requires only a text editor. When the
changes are complete, you can use VISE X to create a new VCT from the data in
the file.
To export VCT data as XML:
1. From the File menu, select Export VCT as XML... A standard Save File dialog will
be displayed. Specify your desired name and location for the export, and then click
Save.
VISE X saves the exported XML as a VISE Export Bundle (file extension .xvct) that contains the following files:
■
A .plist file that describes the attributes of all the items in the VCT
■
A resources file that contains the internal resources of the VCT, such as a custom
installer icon if one has been added to the Installer Settings/Attributes tab
To access the .plist file in a VISE Export Bundle, go to the Finder and locate the bundle.
Hold down the Control key and click on the bundle, then select Show Package Contents.
VISE X User’s Guide
Section 4 Advanced Features
31–2
Creating a VCT from XML
To keep the VISE Export Bundle at a manageable size, VISE X saves
the bundle without compressed data. For that reason, file paths for
all items in the VCT must stay the same for both the export of the
VCT and the creation of a new VCT from the exported data.
Creating a VCT from
XML
To create a new VCT from XML:
1. From the File menu, select Create VCT from XML... A standard Find File dialog
will be displayed. Select your desired VISE Export Bundle, and then click Choose.
2. A standard Save File dialog will be displayed. Specify your desired name and location for the new VCT, and then click Save.
If VISE X detects errors in the VCT creation process, it will write the errors to a log file
named “[VCT Name] Log.txt” in the same location as the new VCT. VISE X will create the
log file only if there are errors to report.
There are two AppleScript commands that you can use to automate
the export of XML and the creation of new VCTs from XML. For
more information, see “Exporting VCT Data as XML” on page 24-12
and “Creating a VCT from XML” on page 24-13.
Chapter 31 Working With VCT Data as XML
VISE X User’s Guide
Section 5
Special Topics
32–1
Chapter 32
Extra Features
VISE X offers a few helper functions that you can use to modify files for purposes other
than creating installers, if desired. These helper functions are available through the Extras
menu, and they enable the following:
Encoding Files as
BinHex, MacBinary
or Tarball
■
Encoding files as BinHex, MacBinary or Tarball
■
Undoing or redoing Mach-O prebindings
Encoding is usually necessary to protect the data forks of Macintosh files before the files
are sent across the Internet or stored on non-Macintosh volumes. You can use VISE X to
encode files as any of the following formats:
■
BinHex (file extension .hqx)
■
MacBinary (file extension .bin)
■
Tarball (file extension .tar.gz)
To encode a file:
1. From the Extras menu, select Encode File.
2. Select one of the following options:
■
As BinHex...
■
As MacBinary...
■
As Tarball...
3. A standard file dialog box will be displayed. Navigate the dialog box until you
select the file you wish to encode.
4. Click Choose.
VISE X User’s Guide
Section 5 Special Topics
32–2
Undoing or Redoing Mach-O Prebindings
5. Enter a name for saving the encoded file, or accept the default.
Illustration 32-1: Encoding a File as MacBinary
6. Choose a location for saving the encoded file, or accept the default.
7. Click Save.
You can set up the Post Processing tab of a Build Target to automatically create a Tarball version of your installer at build time. See “Post
processing tab” on page 21-15 for more information.
Undoing or Redoing
Mach-O Prebindings
Chapter 32 Extra Features
Prebinding is a process that can enable Mach-O executables to launch faster. (Mach-O is
the native runtime format for Mac OS X applications.) VISE X can affect Mach-O prebinding in two primary ways:
■
To compare two prebound files for any differences, VISE X updaters temporarily
undo prebinding from the files. After making the required comparisons, the
updaters redo the prebinding. The updaters make these changes to prebinding
automatically.
■
You can use VISE X to undo or redo Mach-O prebindings.
VISE X User’s Guide
Undoing or Redoing Mach-O Prebindings
32–3
A thorough discussion of prebinding is beyond the scope of this
documentation. See Apple documentation for prebinding information.
To undo or redo Mac OS X prebindings:
1. From the Extras menu, select one of the following options:
■
Undo Mach-O Prebindings
■
Redo Mach-O Prebindings
2. A standard file dialog box will be displayed. Navigate the dialog box until you
select the executable file for the application that needs prebinding changes.
The path to your application’s executable file will probably be similar to the
following example:
/Applications/MyApp.app/Contents/MacOS/MyApp
Illustration 32-2: Undoing or Redoing Mach-O Prebindings
3. Click Choose. A dialog will indicate whether or not the procedure was successful.
VISE X User’s Guide
Section 5 Special Topics
32–4
Chapter 32 Extra Features
Undoing or Redoing Mach-O Prebindings
VISE X User’s Guide
33–1
Chapter 33
Shortcuts and Keyboard Commands
Archive Window
Keyboard Shortcuts
The following table lists keyboard shortcuts for navigating and selecting files within the
Archive Window.
Desired Action
Keyboard Shortcut
Select first item in archive window
item list
Command-up arrow
Select first item in archive window
item list
Command-down arrow
Collapse folder
Command-left arrow
Expand folder
Command-right arrow
Expand all items in a folder
Option-click the triangle next to name
of folder or Option Command right
arrow
Select multiple items that are not next
to each other in the archive
(discontinuous selection)
Command-click
Select multiple items in a group
(contiguous selection)
Shift-click
Arrange multiple items in the archive
window at once
Shift-click on multiple items and drag
them to a new location
Select next item
Down arrow
Select previous item
Up arrow
Scroll up one page
Page up
Table 33-1: Archive Window Keyboard Shortcuts (Sheet 1 of 2)
VISE X User’s Guide
Section 5 Special Topics
33–2
Extended Add Dialog Keyboard Shortcuts
Desired Action
Keyboard Shortcut
Scroll down one page
Page down
Scroll to top
Home key
Scroll to bottom
End key
Open the default folder settings dialog
for that folder.
Double-click on a folder while holding
down the ’D’ key or the ’d’ key.
Table 33-1: Archive Window Keyboard Shortcuts (Sheet 2 of 2)
Extended Add Dialog
Keyboard Shortcuts
The following table lists keyboard shortcuts for navigating and selecting files within the
Archive Window
Desired Action
Keyboard Shortcut
Expand directory
Command-right arrow
Collapse directory
Command-left arrow
Select file by name
Type first characters of name until it
appears selected
Select next item alphabetically
Tab
Select previous item alphabetically
Shift-Tab
Select next drive
Command-shift-right arrow
Select previous drive
Command-shift-left arrow
Expand/collapse directory
Return
Toggle checkbox on/off
Command-down arrow
Add files to archive (same as Add
button)
Enter
Close Add dialog box (same as Done
button)
Escape, or Command-W, or
Command-.
Table 33-2: Extended Add Dialog Keyboard Shortcuts
Drag and Drop
Shortcuts
The following Drag and Drop shortcuts can be used in VISE X:
■
When you drag a file from the Finder into a folder in the archive (other than the
root folder), the item will inherit the package settings of its parent folder in the
archive. For example, if you have an Applications folder in the archive that’s
assigned to the Applications package, dragging a new application into the Applications folder will automatically cause the application to be assigned to the
Applications package.
■
Dragging an item from the Finder into an Action Item Search Criteria will assign
that file's attributes.
■
Dragging an item from the archive window onto an Action Item window (except
Chapter 33 Shortcuts and Keyboard Commands
VISE X User’s Guide
Changing Multiple File Attributes Shortcuts
33–3
message action) will assign the attributes of the file.
■
Changing Multiple
File Attributes
Shortcuts
VISE X User’s Guide
Dragging an .icns file onto the Installer Settings/Attributes tab, Installer icon
area will copy the icons from that file and use them for the custom icon for the
installer.
To change the attributes of several files in the archive at the same time:
1. Select all the files you wish to change.
2. Hold down the Option key while you click Get Info. A blank Get Info window
will be displayed. Any information that you change in this window will be applied
to all the selected files.
Section 5 Special Topics
33–4
Chapter 33 Shortcuts and Keyboard Commands
Changing Multiple File Attributes Shortcuts
VISE X User’s Guide
Index–1
A
B
C
D
E
F
G
H
I
J
K
L
M
N
O
P
Q
R
S
T
U
V
W
X
Y
Index
Symbols
^0 in New Name Field
See New Name 5-26
.icns files 4-21, 10-22
%%
See Variables, percent symbol in 22-7
%InstallVar%
install location variable 22-7, 29-4
%ShellVar%
shell script variable 22-7, 26-22, 26-24
%VariableName%
registration example 28-8
See Variables, declaration of 22-3
$1 UNIX parameter 26-22 to 26-23
$2 UNIX parameter 26-22, 26-24
$3 UNIX parameter 26-22, 26-24
$4 UNIX parameter 26-22, 26-24
A
Action items
about 5-1
and runtime variables 22-6
build directives 5-4
replace options 5-50
search criteria 5-11
search locations 5-10
Action Items Ignore Hidden Items 10-20
Activate (AppleScript) 24-4, 25-1
Active Build Target 21-18
Active Web Installers
See Web Installers 30-1
VISE X User’s Guide
Add 9-24
Add a plist entry 5-40
Add Dialog
changing preference 3-3
extended 3-3
standard 3-2
Add Item... button 19-4, 19-22
Add text to the beginning of file 5-40
Add text to the end of file 5-40
Add To 5-44
Add to Application Menu 10-16
AddObjectToArchive (AppleScript) 24-20
Advanced Project Management
action item build directives 5-4
After Install 10-28
Alias <x> Level(s) Above Found Item 5-25
Alias Location 5-25
Alias Options 5-25
All Disks
search location 5-10
Allow Installation To Mounted Servers 10-19
Allow Installation to UFS Volumes 10-19
Allow Installer Resources To Be Replaced 10-29
Allow Only Single Selections In Custom Install 10-9
Allow Sub-launched Installer Restart 10-19
Allow User To Choose Download Site 10-30, 30-4
Allow User To Choose Invisible Folders 10-19
Also Quit Installer 5-34
Always 9-15
replace options 5-51
Always Create Moved Items Folder 10-19
Always Replace
log file options 10-16
Z
Index–2
A
B
C
D
E
F
G
H
I
J
K
Always Set Install To Install Folder 9-25
Any Match
for action item build directives 4-20, 5-5, 9-16
Append to Existing
log file options 10-16
AppleScript
controlling an installer 25-1
in installers 24-1, 24-4
AppleScript Commands
Activate 24-4, 25-1
AddObjectToArchive 24-20
BringUpToDate 24-5
Build 24-8
BuildDirectiveOff 24-7
BuildDirectiveOn 24-6
BuildTargetOff 24-7
BuildTargetOn 24-7
BUTDValidatePaths 24-5
CloseWindow 24-4
CompareFiles 24-20
CreateNewFolderInArchive 24-21
CreateNewUpdater 24-17
CreateVCTfromXML 24-13
DeleteSelectedItems 24-17
Deselect 25-2
DoInstall 25-2
ExportTranslator 24-9
ExportVCTasXML 24-12
Extract Item 24-6
ImportTranslator 24-10
Open 24-4
OpenSelectedUpdaterItem 24-18
RemoveCompressedData 24-12
SaveArchive 24-4
Select 25-2
SelectArchiveItem 24-14
SelectDrive 25-2 to 25-3
SetAssignPackagesFlag 24-5
SetBillboardMode 24-6
SetBuildTarget 24-6
SetDisk 24-10
SetDownloadSite 24-8
SetInstall 25-1
SetLocalizationFile 24-9
SetSelectedItemInstallLocation 24-16
SetSelectedItemReplaceOptions 24-15
SetUpdaterSourceSpec 24-19
SetUpdaterTargetSpec 24-19
SetVariable 24-8
UpdateDriveList 25-2
ValidateUpdateFile 24-10
Application Bundle 5-16, 9-21, 20-7, 21-10
defining bundle filename extensions 9-21
L
M
N
O
P
Q
R
S
T
U
V
W
X
Y
Z
Applications
localizing on-the-fly 23-26
shutting down before installing 10-18
shutting down on uninstall 10-18
Applications folder
as default install location 10-7
Archive Links 21-19
Archive Reports 12-1, 12-3
output options 12-4
to printer 12-4
to screen 12-4
to text file 12-4
Archive Window
and file/folder options 9-2
editable columns 20-7
item detail 20-2
item list 20-2
keyboard shortcuts 33-1
layout 20-1
list columns 20-3
shortcuts 20-7
vertical column titles 20-2, 20-7
Archives
about 3-1
adding files 3-4
changing names of files 3-5
opening with AppleScript 24-4
saving 3-4
saving with AppleScript 24-4
setting up remove function 9-22
updating 3-6
validating paths 16-4
verifying 3-6, 16-4
Ask If False 5-51, 9-16
Ask User 5-51, 9-15
install to location 9-9
search location 5-10
Assign Parents Package to New Files 16-4
Attributes tab 21-10
Auto-suffix
log file options 10-16
B
Background images 10-16
Before Install 10-28
Billboard Files 11-4
in project window 21-24
Billboards
by disk 11-2
by package 11-2
default 11-5
removing 11-4, 11-6
sequential 11-2
VISE X User’s Guide
Index–3
A
B
C
D
E
F
G
H
I
setting mode via AppleScript 24-6
BinHex files
encoding files as 32-1
Bring Up To Date 9-24, 16-1, 21-8
and embedded VCTs 10-27, 16-4
setting with AppleScript 24-5
BringUpToDate (AppleScript) 24-5
BRM Permit No, City & State
for registration destination 28-3
Build (AppleScript) 24-8
Build Directives
AND condition 4-21, 5-5, 9-16, 21-5
and packages compared 21-1
any match 4-20, 5-5, 9-16
defined 21-1
for billboard files 21-25
for packages 4-10
NEVER condition 21-6
OR condition 4-21, 5-5, 9-17, 21-6
setting for files and folders 9-16
setting with AppleScript 24-7
Build Sources 21-8
Build Target
active 21-18
CFBundleName 21-13
Create Debug 21-11
Dates tab 21-16
Directives tab 21-15
Display Billboards 21-12
duplicating 21-14, 21-19, 30-7
Installer Name 21-12
Language 21-13
Path 21-14
Post processing tab 21-15
Scripts tab 21-16
Settings 21-11
Build Target Format
application bundle 21-10
CD installer (uncompressed) 21-10
disk images 21-10
folders/CD segments 21-10
web installer (w/Data) 21-10
web installers 21-10
Build Targets 21-9
and billboards 21-12
and localization 21-13
duplicating 21-14
for web installers 30-2
VISE X User’s Guide
J
K
L
M
N
O
P
Q
R
S
T
U
V
W
BuildDirectiveOff (AppleScript) 24-7
BuildDirectiveOn (AppleScript) 24-6
BuildTargetOff (AppleScript) 24-7
BuildTargetOn (AppleScript) 24-7
Bundle
action item search criteria 5-11
defining bundle filename extensions 9-21
drag and drop behavior 5-12
search behavior 5-12, 10-7
version checking behavior 5-16, 10-7
Bundle Extensions.txt 9-21
Bundle updaters
removing items from 19-23
BUTDValidatePaths (AppleScript) 24-5
Button
behaviors 27-8
properties 27-7
Button 1 5-27
Button 2 5-27
Button Behavior
cancel 27-8
continue 27-8
display form 27-9
e-mail 27-9
print for fax 27-9
print mailer 27-8
register 27-8
Byte Range Downloads 10-30, 30-4
C
Cache billboards on local drive
billboard display option 11-4
Case Sensitivity
and variables 22-2
Catalog
for web installers 30-12
Catalog Only Installers 10-26
CD Installer (Uncompressed)
Build Target Format 21-10
CD installers
and uncompressed files 9-18
installer settings for 3-4
validating paths for 16-4
verifying archive for 16-4
CFBundleName
build targets 21-13
Check <x> Level(s) Above Found Item 5-45
Check Consistency 23-25
Check for Duplicate 3-6
Check Item Gestalts On Custom Install 10-9
and Language/Region settings 9-6
X
Y
Z
Index–4
A
B
C
D
E
F
G
H
I
J
K
Check Permissions Options 5-45
Checkbox
properties 27-13
cicn
ids in message actions 5-27
in external resource file 5-27
Classic Domain
location definition file 29-1
CloseWindow (AppleScript) 24-4
Comment Options 5-47
Compare button 19-4, 19-22
Compare Creation Dates 5-50, 9-15
Compare Modification Dates 5-50, 9-15
Compare Version 5-50, 9-15, 10-27
CompareFiles (AppleScript) 24-20
Compress Installer 10-26
Confirm Action 5-44
Confirm Before Deleting Files 3-6
Confirm Before Saving 3-6
Confirm Copy 5-21
Confirm Creating Alias 5-25
Confirm Delete 5-20
Confirm Edit File 5-40
Confirm Move 5-22, 5-24
Consistency Information window 23-25
Contextual Menu Items 9-20
Copy <x> Level(s) Above Found Item 5-21
Copy Options 5-20
Copy To Location 5-21
Create Installation Folder Named 10-19, 22-7
Create Log File During Install 10-15
Create Separate Catalog 10-30, 30-3
Create VCT from XML 31-2
CreateNewFolderInArchive (AppleScript) 24-21
CreateNewUpdater (AppleScript) 24-17
CreateVCTfromXML (AppleScript) 24-13
Current Folder
search location 5-10
Custom Install
setting as default 10-2
Custom Mailers
for registration 28-13
D
Debug Installer
building 14-4
L
M
N
O
P
Q
R
S
T
U
V
W
X
Y
Z
Default Billboards 11-5
Default Install Location 10-7, 22-7
Default Installer Settings 10-31
Default Layout 20-3, 20-5
Delete <x> Level(s) Above Found Item 5-19
Delete Folder Only If Empty 5-19
Delete on Uninstalls 20-7
Delete Options 5-19
Delete search text 5-40
DeleteSelectedItems (AppleScript) 24-17
Deselect (AppleScript) 25-2
Diagnostic
archive report 12-3
Disable Strict Library Checking 10-29
Disk Images 21-10
and uncompressed files 9-17
Disk Information
Disk Size 8-2
Segment Size 8-2
Disk Size
setting 8-2
setting with AppleScript 24-10
Display Easy Install Package In Progress 10-9
Display Form Options 5-29
Display Found Items 5-20 to 5-22, 5-24 to 5-25, 5-40, 5-44
Display Invisible Files 3-6
Display Registration 10-16
Dock/Startup Items Options 5-43
DoInstall (AppleScript) 25-2
Domain 5-21, 5-23, 5-26
setting for install location 9-9
Don't Allow Multiple Installs 10-20
Don't Install Folder (Placeholder) 9-21
Don’t Copy Files from Source at Build Time 10-26
Don’t Copy vct Resources 21-23
Don’t Display Lang. Popmenu 10-14
Don’t Shutdown Running Apps on Uninstall 10-18
Don’t Update Packages on Imported VCT Files 10-27, 16-4
Download Sites 30-11
setting with AppleScript 24-8
Drag and Drop 3-6
in Action Items 5-12
shortcuts 33-2
DS_Store file 3-1, 9-20, 10-27, 15-5
E
Easy Install 4-1
and gestalt calls 9-19
text for 10-8
VISE X User’s Guide
Index–5
A
B
C
D
E
F
G
H
I
J
K
Easy Install Package 4-1
Easy Install Text 22-7
Edit Disk 8-1
Edit Disk window 24-10
Edit Easy Install Text 10-8
Edit External Code 6-4, 6-6
Edit Gestalt 7-3
Edit Layout 20-4
Edit Package 4-8
Edit Package Options
can select more than one 4-10
choose icon 4-9
default package on 4-9
description 4-8
gestalt 4-10
Icon ID 4-9
list footer 4-10
list header 4-10
list help 4-10
list package 4-10
must select at least one 4-10
mutual exclusive group 4-9
name 4-8
pad 4-8
restart after installing 4-9
separator 4-9
show in install popmenu 4-9
user flag 4-9
version 4-9
Edit Text File Options 5-39
Edit Text Item
properties 27-12
Edit Uninstall Text 10-11
Email Address
for registration destination 28-4
Email Registration 28-12
Embedded VCTs 21-19
and Bring Up To Date 16-4
don’t copy vct resources 21-23
updating 10-27
Empty Folders
installing 10-20
Encode File 32-1
Encoding
as BinHex, MacBinary or Tarball 32-1
UTF-8 23-4
Event Loop 10-28
exit 1
UNIX shell script command 26-23 to 26-24
Export VCT as XML 31-1
Exporting
translator files 23-25
user resources 23-24
VISE X User’s Guide
L
M
N
O
P
Q
R
S
T
U
V
W
ExportTranslator (AppleScript) 24-9
ExportVCTasXML (AppleScript) 24-12
Extended Add Dialog 3-2
keyboard shortcuts 33-2
Extended Add Dialog Box 3-3
Extended Comment 5-47
External code
adding to an installer 6-2
localized 23-24
External Code Is Optional 10-29
External code resources
ID number range 26-2
in foreign-language installers 23-24
marking 26-18
External codes
assigning to the installer 10-28
checking for cancellation 26-19
declaring in an installer 6-3
hints for using 26-17
nonexistent or misidentified 26-2
specifying when to call 6-6
types that can be called 26-1
using multiple 26-2
when they can be called 26-1
Extract Item (AppleScript) 24-6
F
File
action item search criteria 5-10 to 5-11
File creator
changing 9-7
File is invisible 20-7
File is Locked 20-7
File type
changing 9-6 to 9-7
File versions 18-1
Files
archive report 12-3
changing attributes of multiple 33-3
default install locations for 9-13
deleting during uninstalls 9-20
installing based on gestalts 9-18
invisible 3-6
replacing during installation 9-14
Find 13-3
items within an archive 13-1
Find Action items
for default install location 10-7
installing items based on 9-7
installing items to result location 9-12
Find Action Result
install to location 9-9
search location 5-10
X
Y
Z
Index–6
A
B
C
D
E
F
G
H
I
J
K
L
M
Find Multiple Occurrences 5-11, 5-20 to 5-22, 5-24 to 5-25
Find Options 5-18
Find Previous 13-3
Finish playing last movie
billboard display option 11-4
Folder
action item search criteria 5-10 to 5-11
Folder Default Settings 5-51, 9-23, 10-27
notes on functionality 9-24
removing 9-24
setup 9-23
Folders
and uncompressed files 9-17
installing based on gestalts 9-18
installing to archive folders 9-13
replacing during installation 9-14
storing uncompressed 9-17
Folders/CD Segments 21-10
Force QD Drawing Refresh 10-20
Force Restart when Appropriate 10-18
Force Scroll before Continue 10-14
Form
localization 27-3
Form Name 5-29
Full Path Name 24-4
G
Generic Interface 10-3
Gestalt
OR condition 9-19
Gestalts 7-3, 20-7
and Easy Install 9-19
creating 7-3
installing items based on 9-18
Get Info window 4-21, 9-2, 9-17
Group and Permissions 9-25
H
Hide on Startup 5-44
Hide Progress Bar 5-36
High ASCII characters 23-4
HTTP 1.0
and active web installers 30-2
I
Icon
for message action dialogs 5-27
Icon ID 5-26
Icon positioning 3-1, 15-5
Icons
for packages 4-21
N
O
P
Q
R
S
T
U
V
W
X
Y
Z
If 9-16
If Different 5-50, 9-15
replace options 5-50
If Exists 5-50, 9-15
If Newer 5-50, 9-15
If Newer or Equal 5-50, 9-15
If Older 5-50, 9-15
If Older or Equal 5-50, 9-15
Ignore DS_Store Files 10-27
Ignore Hidden Files 10-27
Import
other resources 23-25
Importing Other Resources 23-25
ImportTranslator (AppleScript) 24-10
In Installer 30-10
Include On-line Registration Module 10-16
Individual File 30-10
Initial install location
setting 10-7
Initialization 10-28
Insert after search text 5-40
Insert before search text 5-40
Insk Resource 23-31
Install Empty Folders 9-13, 9-21, 10-20
Install Folder
install to location 9-9
search location 5-10
Install Locations 29-1
archive report 12-3
Installer file
available languages 23-1
Installer Interface 10-2
Installer Password 10-23
Installer Quit 10-28
Installer Settings 10-1
defaulting 10-31
deleting 10-34
saving 10-30
selecting 10-31
Installers
adding background images 10-17
adding splash screens 10-17
and AppleScript 24-1, 24-4
building with AppleScript 24-8
creating remove functions 9-22
default install location 10-7
on CD 15-5
supported languages 23-2
InstallVar 22-7, 29-4
Interface Options
generic 10-2
installer 10-2
updater 10-2
VISE X User’s Guide
Index–7
A
B
C
D
E
F
G
H
I
J
K
L
Invisible files 3-6
Item Detail 20-2
Item List 20-2
J
Jump Action 5-32
K
Keyboard equivalents
find 13-3
find next 13-3
find previous 13-3
Keyboard shortcuts 33-1 to 33-2
kSelectorCheckingSizes 26-17
L
Language
action option 5-6
and Build Targets 21-13
and Check Item Gestalts On Custom Install 9-6
file and folder option 9-6
for billboard files 21-25
user defined 23-31
Language and Region
AND condition for actions 5-6
AND condition for files 9-7
OR condition for actions 5-6
OR condition for files 9-7
Language Codes
for VISE X 23-27
Language encoding
UTF-8 23-4
Language file 23-2
Language In Archive 21-13
Launch URL Options 5-38
Launch URL Path 5-38
Layout 20-1
default layout 20-5
reordering 20-3
samples 20-5
separators 20-5
setup 20-4
standard layout 20-5
Layout List 20-3
License Agreements
adding to the installer 10-11, 10-13
in project window 21-23
viewing 21-23
List Columns 20-3
List packages
about 4-7
headers and footers 4-13
VISE X User’s Guide
M
N
O
P
Q
R
S
T
U
V
W
X
Y
Z
Help PICTs for 4-14
Local Domain
location definition file 29-1
Local Domain Extended
location definition file 29-2
Localization
and build targets 21-13
features 23-1
of applications 23-26
of registration forms 28-8
Localization file 23-2
setting with AppleScript 24-9
Localized External Code
in multi-language installers 23-24
in single-language installers 23-24
Lock Name 9-23
Log File 10-15
Log File Name 10-15, 22-7
Log File Options
always replace 10-16
append to existing 10-16
auto-suffix 10-16
Long Name 9-6
changing 9-6
M
MacBinary files
encoding files as 32-1
Mach-O Prebindings
undoing or redoing 32-2
Mail To
for registration destination 28-3
Mailer Registration 28-12
Main Window
supress options 10-5
Match Can be Alias 5-11
Message Options 5-26
Minimum Requirements To Install
Allow User To Override Minimum Requirements 10-23
Minimum Requirements to Install
CPU 10-23
Quit Installer if Not Administrator 10-23
Require OS X Authentication 10-23
System Version 10-23
Modify File Date When Merging Resources 10-20
Move <x> Level(s) Above Found Item 5-22
Move Options 5-22
Move To Location 5-22
Moved Items Folder 10-19
Moving Across Volumes 5-23
Multi-language Installers
and billboards 11-5
steps to create 23-3
Index–8
A
B
C
D
E
F
G
H
I
J
Multiple file attributes, changing 33-3
Multiple Users Accounts
support for 10-35
Mutual exclusive group 4-10
N
Name 5-47
for alias actions 5-26
Nested Folders
and folder default settings 9-24
Network Domain
location definition file 29-1
Network Domain Extended
location definition file 29-2
Never 5-51, 9-15
New Billboard File 11-5
New Name 5-21, 5-24, 5-26
No Restart Warnings 10-19
None (interface option) 10-4
NT
and shadow items 9-5
O
Only Store Catalog of Files 3-4, 15-2
Open (AppleScript) 24-4
Open After Installing 9-20, 20-7
Open/Launch Found Items 5-18
OpenSelectedUpdaterItem (AppleScript) 24-18
OS X Dock 5-44
Other
install to location 9-9
Other Resources
import 23-25
Override Language 23-26
P
Package Build Directives 4-10, 4-20
and sub-packages 4-21
Package Dependencies 4-3, 4-5
and AppleScript 25-2
Packages 5-36, 20-7
about 4-2
adding icons 4-22
and build directives compared 21-1
and runtime variables 22-7
archive report 12-3
assigning gestalts 4-14
creating on-the-fly 4-24
deleting 4-23
edit package options
can select more than one 4-10
choose icon 4-9
K
L
M
N
O
P
Q
R
S
T
U
V
W
X
Y
Z
default package on 4-9
description 4-8
gestalt 4-10
Icon ID 4-9
list footer 4-10
list header 4-10
list help 4-10
list package 4-10
must select at least one 4-10
mutual exclusive group 4-9
Name 4-8
pad 4-8
restart after installing 4-9
separator 4-9
show in install popmenu 4-9
user flag 4-9
version 4-9
removing items from 4-24
Packages popmenu 4-24
Password
for installer 10-23
Path
build targets 21-14
Paths
validating 16-4
Perform Numeric Comparison 5-31
Permissions and Group 9-25
Picture
properties 27-17
Placeholder Folders 9-21, 20-7
PlugIns/Scripts
in project window 21-26
Post Processing 21-15
Prebinding
undoing or redoing 32-2
Preferences
default installer settings 10-33
setting options 3-6
Preventing application shutdown 26-20
Print For Fax Registration 28-12
Progress Stop
supress options 10-5
Q
Quit Installer if Find Fails 10-7
R
Radio Button
properties 27-14
Radio Group
properties 27-16
VISE X User’s Guide
Index–9
A
B
C
D
E
F
G
H
I
J
K
L
Read Me Files
adding to the installer 10-11 to 10-12
in project window 21-23
viewing 21-23
Read plist entry to variable 5-41
Read text to variable 5-41
Redo Mach-O Prebindings 32-3
RefCon 26-2
Region
action option 5-6
and Check Item Gestalts On Custom Install 9-6
file and folder option 9-6
Region Codes
for VISE X 23-28
Region(s)
for registration destination 28-3
Registration Destination 28-3
BRM Permit No, City & State 28-3
email address 28-4
mail to 28-3
region(s) 28-3
reply address 28-4
subject 28-4
zip code for bar code 28-3
Remove From 5-44
Remove function 9-22
text for 10-11
Remove plist entry 5-40
RemoveCompressedData (AppleScript) 24-12
Rename <x> Level(s) Above Found Item 5-24
Rename Existing 5-51, 9-16
Rename Options 5-23
Replace 5-21, 5-23 to 5-24, 5-26, 9-14, 9-25
Replace Defaults 10-27
Replace options 5-21, 5-23 to 5-24, 5-26, 5-50, 9-14
always 5-51, 9-15
ask if false 5-51, 9-16
ask user 5-51, 9-15
compare creation dates 5-50, 9-15
compare modification dates 5-50, 9-15
compare version 5-50, 9-15
if different 5-50, 9-15
if exists 5-50, 9-15
if newer 5-50, 9-15
if newer or equal 5-50, 9-15
if older 5-50, 9-15
if older or equal 5-50, 9-15
never 5-51, 9-15
VISE X User’s Guide
M
N
O
P
Q
R
S
T
U
V
W
rename existing 5-51, 9-16
Replace plist entry 5-41
Replace search text 5-40
Reply Address
for registration destination 28-4
Report Output Options 12-4
Resource exceptions 19-4
about 18-2, 19-9
default 19-8
entering information 19-11
for updaters 19-9
Resource Files
in project window 21-24
Resource of Archive 11-5
Resources
identification of 19-7
merging for localization 23-26
Restart 10-18
Restart After Installing 9-20, 20-7
Return <x> Level(s) Above Found Item 5-18
Return Parent of Found Item 10-7
Root of Startup Disk
install to location 9-9
search location 5-10
Runtime Variables 22-2
S
Save as POSIX Path 5-19
SaveArchive (AppleScript) 24-4
scpt 24-1
Script.h 23-29
SdEx resource 26-20
Search Criteria
action item 5-11
Search for Text/Key 5-41
Search location popmenu 5-10
Search Locations
all disks 5-10
ask user 5-10
current folder 5-10
find action result 5-10
install folder 5-10
root of startup disk 5-10
Search Locked Volumes 5-11
Search Subfolders 5-11
Search/Replace
Source paths option 21-9
X
Y
Z
Index–10
A
B
C
D
E
F
G
H
I
J
K
Select (AppleScript) 25-2
Select All Found 13-3
Select Volumes Only 10-3
SelectArchiveItem (AppleScript) 24-14
SelectDrive (AppleScript) 25-2 to 25-3
Selected Disk 5-10
Send Install Location 5-36
Separators 4-10
Set Localization File 10-28
Set Owner To Root 20-7
Set Variable 5-19
Set Variable Options 5-29
SetAssignPackagesFlag (AppleScript) 24-5
SetBillboardMode (AppleScript) 24-6
SetBuildTarget (AppleScript) 24-6
SetDisk (AppleScript) 24-10
SetDownloadSite (AppleScript) 24-8
SetInstall (AppleScript) 25-1
SetLocalizationFile (AppleScript) 24-9
SetSelectedItemInstallLocation (AppleScript) 24-16
SetSelectedItemReplaceOptions (AppleScript) 24-15
Settings
for Build Targets 21-11
Settings... button 19-4
Setup Defaults 9-24
SetUpdaterSourceSpec (AppleScript) 24-19
SetUpdaterTargetSpec (AppleScript) 24-19
SetVariable (AppleScript) 24-8
Shadow Items 9-3
and NT 9-5
ShellVar 22-7
Show “Select All” Button In Custom Install 10-9
Show Billboards 5-36
Show Easy Install Package in Custom Install 10-9
Show License Agreement 5-36
Show Read Me 5-35
Show Select Folder 10-4
Show Size in 10-27
Show Sizes in Easy Install 10-9
Show Splash Screen 5-35
shsc 26-23
Shutdown Applications Before Installing 10-18
Single-language installers 23-4, 23-12
steps to create 23-3
Source items
customer modifications to 19-6
defined 18-1
renaming customer’s 19-12
Source paths 21-8
Search/Replace option 21-9
Specific Packages
archive reports 12-3
L
M
N
O
P
Q
R
S
T
U
V
W
X
Y
Z
Splash screens 10-16
Standard Layout 20-5
Startup Disk 5-10
Startup Items 5-44
Stop Install With Error 5-34
Stop Installation Action Options 5-34
Strict Installer Data Time Stamp Checking 10-30, 30-3
Subject
for registration destination 28-4
Sub-launch locks 5-35 to 5-36
Sub-launched item is a VISE X Installer 5-35
Sub-packages
about 4-2
and package build directives 4-21
creating 4-11
Success
supress options 10-5
Suppress 5-36
Suppress Internet Dialup Dialog 30-3
Suppress Internet Disconnect Dialog 10-30, 30-4
Suppress User Interface 10-6
Supress Internet Dialup Dialog 10-30
Symbolic Link 9-23, 20-7
Synchronize Dates 9-21, 20-7, 21-17
System Domain
location definition file 29-1
System Domain Extended
location definition file 29-2
System Extensions
and uninstalls 9-20
T
Tarball files
encoding files as 32-1
post processing 21-15
Target
active 21-18
Target files
removing 19-5 to 19-6, 19-23
Target items
adding 19-5, 19-23
defined 18-1
options for naming 19-12
Test Update... button 19-4
Test Variable Options 5-31
Text to Add/Append/Replace 5-41
To Printer
archive report option 12-4
To Screen
archive report option 12-4
To Text File
archive report option 12-4
VISE X User’s Guide
Index–11
A
B
C
D
E
F
G
H
I
J
K
L
M
Translator applications 23-2
consistency check 23-25
Translator file
exporting with AppleScript 24-9 to 24-10
Translator XML file 23-2
consistency check 23-25
exporting 23-25
Trash Can 19-4, 19-22
U
Uncompressed Files Are Optional 10-20
Undo Mach-O Prebindings 32-3
Uninstall Text 22-7
Uninstalls 9-22
on Mac OS X 9-20
text for 10-11
Universal binary installers 1-1
Universal installers 1-1
UNIX $1 parameter 26-22 to 26-23
UNIX $2 parameter 26-22, 26-24
UNIX $3 parameter 26-22, 26-24
UNIX $4 parameter 26-22, 26-24
UNIX Script 5-48
UNIX Script Options 5-48
UNIX scripts
executing from the installer 26-21
Update Archive Files With Any Difference 10-27
Update Archive See Bring Up To Date
Update Only Files Already In The Archive 10-27
UpdateDriveList (AppleScript) 25-2
Updater Interface 10-3
using 19-15, 19-31
Updater items
building 19-14
presentation options for installers with 19-16, 19-32
removing items from 19-5 to 19-6
testing 19-14
Updater Settings 19-11
Updaters
about 17-1
adding items 19-5, 19-22
benefits and features 17-2
components of 18-1
customer’s perspective 17-2
designing 18-1
integration with VISE X 17-2
localization features 17-2
Why use updaters? 17-1
Why use VISE X? 17-1
Updating
user resources 23-24
Updating an Archive 3-6
Upload Cab File(s) To Web Server At Build Time (FTP sites
VISE X User’s Guide
N
O
P
Q
R
S
T
U
V
W
X
Y
only) 10-30, 30-3
Use Custom Icon 20-7
Use Extended Add File Dialog Box 3-6
Use Replace Defaults 5-51, 9-25, 10-27
Use the “Applications” folder by Default 10-7
Use Updater Interface 19-2, 19-20
Use Yes/No for Action Item Confirmations 10-19
User Defined Languages 23-31
User Domain
location definition file 29-1
User Domain Extended
location definition file 29-2
User Prompt 5-18, 5-20 to 5-22, 5-24 to 5-25, 5-40, 5-44
USER resources
in foreign-language installers 23-24
UTF-8 encoding 23-4
V
Validate Paths 16-4, 21-8
ValidateUpdateFile (AppleScript) 24-10
Variable “InstallVar”
install to location 9-9
Variables 22-2
and case sensitivity 22-2
declaration of 22-3
InstallVar 22-7, 29-4
percent symbol in 22-7
ShellVar 22-7
VCT Link Options 21-20
Verify Archive 16-4
Verifying an Archive 3-6
Vertical Column Titles 20-2, 20-7
VISE Moved Items 10-19
VISE X
about 1-1
new features in version 5.0 1-2
VISE X Additional Locations folder 29-2
VISE X Extensions folder 2-3
VISE X Extras folder 26-2
VISE X Locations folder 2-3, 29-1
VISEICat 30-13
VISEICat.idx 30-13
W
Wait for sub-launched item to complete 5-35
Web Installer (w/Data) 21-10
Web Installers 21-10, 30-1
assigning files to file groups 30-9
benefits 30-1
build target 30-2
catalog 30-12
download sites 30-11
Z
Index–12
A
B
C
D
E
F
G
H
I
J
In Installer 30-10
Individual File 30-10
self updating 30-3, 30-12, 30-18
setup overview 30-2
user’s initial experience 30-14
user’s subsequent experiences 30-17
What to <Action>
using a find action item 5-7
using archive item 5-8
with items found using search criteria 5-7
K
L
M
N
O
P
Q
R
S
T
U
V
W
X
Y
Z
X
xCustom Location
location definition file 29-1
Z
Zip Code For Bar Code
for registration destination 28-3
VISE X User’s Guide
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertising