George Goh

Overview

The Kusu installer is the first program that is run when the user boots from a Kusu ISO. It is a wizard-style program responsible for collecting the initial information that will describe and set up a Kusu cluster, including the timezone, networks, root password, disk partitioning, and kits available.

The Kusu installer is made up of 2 parts: the screens (context-specific info and prompts), and the navigation framework. In this document, I will describe the screens.

Note: The installer relies heavily on the python snack module to display its screen elements, so some knowledge of that toolkit is required.

Creating the screens

The standard Kusu installer has a total of 11 screens that are stored in a ScreenFactoryImpl class' attribute called ScreenFactory.screens. Inserting a screen in this list will cause the installer to display it with the other screens in the order defined.

A screen is basically described by a subclass of the InstallerScreen. A simple example is the RootPasswordScreen class:



Most of the elements in this screen are auto-generated by the Kusu Framework, so we concentrate on the specific needs of this screen:

• Instruction for the user
• Password entry and verification input fields
• 'Clear All' button for the input fields

Buttons are defined differently from other elements on the screen, so we define the 'Clear All' button on this screen first.

User-defined buttons are defined in the class variable 'buttons', and the callbacks on the buttons are defined in the setCallbacks method:

RootPasswordScreen::setCallbacks

Code:

buttons = [_('Clear All')]
 
def setCallbacks(self):
"""
 
Implementation of the setCallbacks interface defined in parent class
screenfactory.BaseScreen. Initialise button callbacks here.
 
"""
self.buttonsDict[_('Clear All')].setCallback_(self.clearAllFields)

Next are the instruction and entry fields. These are defined and laid out on-screen in the drawImpl method (where self.msg='Please enter a secure root password:'):

RootPasswordScreen::drawImpl

Code:

def drawImpl(self):
self.screenGrid = snack.Grid(1, 3)
entryWidth = 20
self.password0 = kusuwidgets.LabelledEntry(
labelTxt=_('Enter root password ').rjust(26),
width=entryWidth, password=1
)
 
self.password1 = kusuwidgets.LabelledEntry(
labelTxt=_('Verify root password ').rjust(26),
width=entryWidth, password=1
)
 
self.screenGrid.setField(snack.TextboxReflowed(
text=self.msg,
width=self.gridWidth),
col=0, row=0, anchorLeft=1
)
self.screenGrid.setField(
self.password0, col=0, row=1, anchorLeft=1,
padding=(0,1,0,0)
)
self.screenGrid.setField(
self.password1, col=0, row=2, anchorLeft=1,
padding=(0,0,0,1)
)
 

Inserting the screen into the display order

As mentioned earlier, a screen is inserted into the ScreenFactory.screens attribute of the ScreenFactoryImpl class in the order that it should be displayed.

In the following code segment, we see that the root password screen is placed as the 8th screen in the Kusu installation sequence:

ScreenFactoryImpl

Code:

class ScreenFactoryImpl(ScreenFactory):
"""The ScreenFactory is defined by the programmer, and passed on to the
KusuInstaller class.
"""
 
...
 
ScreenFactory.screens = \
[WelcomeScreen(kiprofile=kiprofile),
LanguageSelectionScreen(kiprofile=kiprofile),
KeyboardSelectionScreen(kiprofile=kiprofile),
NetworkScreen(kiprofile=kiprofile),
GatewayDNSSetupScreen(kiprofile=kiprofile),
FQHNScreen(kiprofile=kiprofile),
TZSelectionScreen(kiprofile=kiprofile),
RootPasswordScreen(kiprofile=kiprofile),
PartitionScreen(kiprofile=kiprofile),
ConfirmScreen(kiprofile=kiprofile),
KitsScreen(kiprofile=kiprofile)
]
 
...

Hooks

Through examination of the InstallerScreen class, you will find that it is inherited from the BaseScreen class.

The BaseScreen class contains the following hooks:

[table="head;width=70%"]Function name|Documentation
def drawImpl(self) | Children implement this method to draw their required widgets onscreen. Don't draw the buttons as well, this is already done for you. |
def validate(self) | Validation checks(if any) for user inputs should be here. validate() is called by the framework after the 'Next/Finish' button is pressed on the UI.
def rollback(self) | Rollback method actions called to rollback changes made in this screen. rollback() is called by the framework after the 'Prev' button is pressed on the UI.
def formAction(self) | This method is called by the framework when the 'Next' or 'Finish' button is pressed on this screen.
def executeCallback(self, obj) | Callbacks for objects other than buttons. This is an advanced operation for screens that have widgets that need to handle callbacks.
[/table]

The most commonly used methods from this set are: drawImpl, validate, and formAction. drawImpl has already been discussed, so let's move on to validate and formAction.

validate method

The validate method contains screen-specific logic to validate the inputs given by the user. The Kusu installer framework expects a tuple to be returned from this method in the form of (boolean, string). The first member of the tuple denotes the success of the validate method, and the second is the error message that will be displayed to the user on validation failure.

formAction method

The formAction method is called by the Kusu installer framework when the user clicks on the Next/Finish button of that screen. Typically, this is used to store the values entered by the user to a database.