NBI Tutorial

This document describes how to create and customize own NBI (NetBeans Installer) for your platform application.

Contents


Creating base project

NBI (NetBeans Installer) is project that enables user to create simple installer for his own application from the NetBeans IDE. The base installer can be simply created by one click.

But we have to start from project what we will create installer for. We can choose from two kinds of projects, Module Suite and NetBeans Platform Application. For other projects the installer cannot be created simply from IDE. We will choose NetBeans Platform Application project, but don't worry to work with the second one, the work on installer doesn't differ. Also you can start working on NetBeans Platform Application project and then switch to Module Suite in project properties - Application tag then choose Create Collection of Add-on Modules for Module Suite or Create Standalone Application for NetBeans Platform Application.


Create simple installer

Since we have created project we can set up the basic installer configuration. Just right-click on project, click on Properties and then select Installer category. Here you can set up for what platform you want the installer will be generated. You can select from Windows, Linux, Mac OS X and Solaris (all supported platforms). Next you can specify the license which will be shown while installation. Available are CDDL 1.0, GPL v2, CDDL 1.0 + GPL v2 with ClassPath Exception and Apache License Version 2.0. Of course you can select your own license file or to do not show license at all, in that case the license panel is skipped in the installation wizard. The third and last thing you can set up here is the possibility of pack200 compression which can significantly decrease final installer size.

Project properties dialog

That was all you can do from IDE. Other customization you have to do manually. To build installers right-click on the project and select Package as - Installers.

Installers you can find in <Project folder>/dist. Note that the zip is always created.


Installer panels and action overview

There are six panels (actions) in base in the installer.

Welcome panel

This is a simple panel that shows only some Welcome text. The org.mycompany.installer.wizard.components.panels.WelcomePanel class is responsible for this panel. Because of it's in NBI project you can edit it.

image:Nbi-tutorial-welcome-panel.png

Licenses panel

In this panel the user has to confirm license agreement otherwise he isn't allowed to continue in installation. This panel isn't mandatory. You cannot edit it because it's already precompiled in nbi-engine.jar. It's default panel from NBI engine.

image:Nbi-tutorial-licenses-panel.png

Destination panel

This panel is also default from NBI engine and isn't simply editable. User has to specify where to install application on this panel and if he wants to create desktop icon and start menu shortcut.

image:Nbi-tutorial-destination-panel.png

Pre-install summary panel

This panel only summarizes where the application will be installed and what size will be used for it. It's editable - the org.mycompany.installer.wizard.components.panels.PreInstallSummaryPannel class is responsible.

image:Nbi-tutorial-pre-install-panel.png

Install action

This is the most important part of installation. InstallAction is responsible for the installation itself and shows progress to the user. It isn't editable. It's also precompiled in nbi-engine.jar library.

image:Nbi-tutorial-install-action.png

Post-install summary panel

Very simple panel. Only tell the user if the installation finished properly. Also there is an option to launch installed application after closing installation. Sometimes it's useful to disable this option which is quite simple and it's possible, because this panel is editable - org.mycompany.installer.wizard.components.panels.PostInstallSummaryPanel.

image:Nbi-tutorial-post-install-panel.png


Rebranding and customization

If you want to more customize the installer and rebrand it you have to do changes directly in a NBI project. For generating installers for platform applications there is the NBI project located in NetBeans installation folder - harness/nbi/stub/ext/engine. You can open it in your NetBeans IDE, it's an ordinary Java Application project. You may will need to resolve reference problem - missing NBI engine library. Go to project properties and add library <NetBeans installation directory>/harness/modules/ext/nbi-engine.jar

Important note

When working on NBI project under harness remember that it's shared for all projects you are developing in IDE that harness belongs! Therefore I recommend you to backup the harness/nbi folder.

Labels

The basic thing you might want to customize is to change some labels and texts in installer panel. Also it's the easiest customization. Everything you have to do is edit the Bundle.properties files. Where they are located you can see in a tree below:

image:Nbi-tutorial-tree2.png

Every Bundle.properties file belongs to all classes in the same package. In NBI project it's important only org.mycompany.installer.wizard.components.panels where are three classes: PostInstallSummaryPanel, PreInstallSummaryPanel and WelcomePanel. In Bundle.properties is ordinary properties file which contains list of keys and values. In our case we don't need to change any keys but we are interested only in values. Which key belongs to which class you can recognize by key prefix.

Class Key prefix
PostInstallSummaryPanel PoISP
PreInstallSummaryPanel PrISP
WelcomePanel WP


Good feature is that you can use HTML tags in all labels. Especialy good for formatting and proper spacing.

For example, we want to extend text on welcome panel. How it looks like you can see on the image above. In bundle properties:

<html>\
<h1>Welcome to {product-name} Installer Wizard</h1><br>\
This program will install {product-name} application on your computer.<br><br>\
Click Next to continue.

Note: There are backslashes at the end of some lines. It says that the value continues at the next line.

But we want to add short description as new paragraph and in bold:

<html>\
<h1>Welcome to {product-name} Installer Wizard</h1><br>\
This program will install {product-name} application on your computer.<br><br>\
<b>This SampleApp is only dummy application for playing with installer</b><br><br>\
Click Next to continue.

And here is the result:

image:Nbi-tutorial-welcome-label.png

Rebranding

To change images and icon in NBI is quite simple. You have to only replace images in project. The only thing you have to know where are pictures located and which is which in installer.

We have these images in default installer:

File name Package Image Description
wizard-description-background-left.png org.mycompany.installer.wizard image:Wizard-description-background-left.png Shown on all standard panels in top left corner.
wizard-description-background-right.png org.mycompany.installer.wizard image:Wizard-description-background-right.png Shown on all standard panels in top right corner.
wizard-icon.png org.mycompany.installer.wizard image:Wizard-icon.png Shown on all panels - windows frame icon. Also shown as icon in taskbar. Instead of there is 16x16px icon in windows frame I recommend to use bigger icon 32x32px because of task-bar icon dimensions.
welcome-left-bottom.png org.mycompany.installer.wizard.components.panels.resources image:Welcome-left-bottom.png Shown only on welcome panel in left bottom corner.
welcome-left-top.png org.mycompany.installer.wizard.components.panels.resources image:Welcome-left-top.png Shown only on welcome panel in left top corner.


Where you can find these images in NBI project tree:

image:Nbi-tutorial-tree1.png


Below you can see where are images placed in installer:

image:Nbi-tutorial-default1.png

If you use your own images, they can have other dimensions than the original. The NBI will resize panels to fit with new images. You can see it in sample NBI project (rebranded only).

Three pictures show how our rebranded installer looks like:

image:Nbi-tutorial-rebranded-welcome.png

Installer window resize

The last basic customization is window resizing. Same as rewriting labels you do it in property file, concretely in data/engine.properties. Generally you can set up more properties in this file, but window sizes are the most interesting.

Editable are really only the window frame width and height. You can set standard and minimum sizes. The standard are the initializing dimensions and the minimum tell the installer how small it can be and never will be smaller. If you looked into engine.properties you've sure noticed that there are several values for both width and height. It's because of there are more Look & Feel motives available and every L&F fits with different frame size. Default sizes:

nbi.wizard.ui.swing.frame.width.default=600
nbi.wizard.ui.swing.frame.height.default=500
nbi.wizard.ui.swing.frame.width.win.classic=588
nbi.wizard.ui.swing.frame.height.win.classic=442
nbi.wizard.ui.swing.frame.width.win.xp=600
nbi.wizard.ui.swing.frame.height.win.xp=450
nbi.wizard.ui.swing.frame.width.motif=624
nbi.wizard.ui.swing.frame.height.motif=470
nbi.wizard.ui.swing.frame.width.metal=624
nbi.wizard.ui.swing.frame.height.metal=470
nbi.wizard.ui.swing.frame.width.aqua=640
nbi.wizard.ui.swing.frame.height.aqua=480
nbi.wizard.ui.swing.frame.width.gtk=704
nbi.wizard.ui.swing.frame.height.gtk=528
nbi.wizard.ui.swing.frame.width.nimbus=624
nbi.wizard.ui.swing.frame.height.nimbus=512

Note: I don't recommend you to change sizes if it isn't really needed because it isn't easy to properly setup sizes for all L&Fs.

Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo