When a login template form is specified the PS_OPENAPP dialog performs the following tasks:

• Reads the template's OIWINEXE definition.
• Hides its own controls.
• Applies the following WINDOW properties from the template to itself:
  • Width
  • Height
  • Text
  • BackColor
  • Icon
  • Image
• Creates the controls defined in template on itself and preserves their tab order.

• It must belong to the SYSPROG application. This requirement is essential because during the primary boot login phase an application has not been specified, so the only reliable execution environment at that point is SYSPROG (and even this isn't fully initialized).
• The login template form should not have any WINDOW events defined - these will not be executed because they might interfere with the events in PS_OPENAPP itself.
  • Although you cannot have a CREATE event execute from the login template you can provide a control called INITLOGIN that responds to an INITLOGIN OMNIEVENT call. This will be triggered by PS_OPENAPP before it is displayed and is an ideal location to perform any needed initialization (an example of this can be found below).
• Controls in the login template can have Event Scripts and QuickEvents defined and they will be triggered as normal. However, the latter are scanned for commuter module calls when created and any references to @WINDOW and @COMMUTER will be resolved to the name of the template's CommuterModule property (if they were left unresolved they would point to "PS_OPENAPP" at runtime, which would probably result in unintended behavior).
• The login template to use may be specified in an RXI file, on the command line via a switch, or in the Application Settings dialog.

In order to login into an application successfully it is necessary for the controls on the template to interact with the original hidden controls on PS_OPENAPP. The critical controls for this are:

• LST_APPIDS (Listbox containing the application names)
• EDL_USERNAME (Editline containing the username)
• EDL_PASSWORD (Editline containing the password)
• CHK_RUNAPP (Checkbox to denote if the application is opened or executed)
• BTN_OK (PushButton to trigger the login attempt)

In order to authenticate properly the controls defined for the login template must:

• Set LST_APPIDS to the application ID to access.
• Set CHK_RUNAPP to the desired mode (Checked for RUN, unchecked for OPEN).
• Transfer the entered username to EDL_USERNAME.
• Transfer the entered password to EDL_PASSWORD.
• Execute BTN_OK's CLICK method.

To illustrate this properly the system includes source for a sample login template form and commuter module called RTI_EXAMPLE_LOGIN_TEMPLATE described below.

This is a simple dialog and associated commuter module which demonstrates how a login template works by performing the following tasks:

• Setting LST_APPIDS to "EXAMPLES" so that this dialog always loads the EXAMPLES app.
• Ensuring that CHK_RUNAPP is always checked so that the application is always in RunMode rather than opened to the IDE.
• Collect the credentials from the user and trigger the authentication attempt.

The first two tasks are taken care of by the hidden INITLOGIN control that PS_OPENAPP uses in place of the template's CREATE event, while the latter task is performed when the OK button is clicked.

RTI_EXAMPLE_LOGIN_TEMPLATE

The login template contains the following controls:

• USERNAME_LABEL
• PASSWORD_LABEL
• USERNAME (EditLine used to collect the username)
• PASSWORD (EditLine used to collect the password from the user)
• LOGIN_BUTTON ("Default" PushButton used to trigger the login attempt)
• CLOSE_BUTTON ("Cancel" PushButton used to close the dialog)
• INITLOGIN (Hidden Static control used to initialize the dialog in lieu of a CREATE event)
• The form itself has:
  • Custom title text
  • An Icon
  • A Gradient BackColor
  • A translucent background Image

All event code for these controls is handled by QuickEvents, which in turn reference the form's commuter module stored procedure (also called RTI_EXAMPLE_LOGIN_TEMPLATE).

• As mentioned above all @WINDOW and @COMMUTER placeholder tokens in the QuickEvent definitions are replaced by the string "RTI_EXAMPLE_LOGIN_TEMPLATE" when PS_OPENAPP creates the controls, thereby resolving these references to the correct target at runtime.

The RTI_EXAMPLE_LOGIN_TEMPLATE form includes a hidden STATIC control called "INITLOGIN" and, as mentioned above, PS_OPENAPP looks for a control with this name and triggers its OMNIEVENT event with a message called "INITLOGIN". This OMNIEVENT event is also passed the create parameters that PS_OPENAPP itself was passed:

Here is an excerpt from the RTI_EXAMPLE_LOGIN_TEMPLATE commuter module that shows LST_APPIDS being set to "EXAMPLES", and CHK_RUNAPP being checked in the INITLOGIN OMNIEVENT handle:

    
/////
// initLogin_OnOmniEvent_initLogin subroutine//
////
// INITLOGIN OMNIEVENT message handler for the INITLOGIN control//
////
//    1) Check that we have an EXAMPLES application and select it//
//    2) Force it into run mode//
////
// ----------------------------------------------------------------------------//
// [i]   param1 : CreateParam.  Contains the original parameters as passed to //
//              : the "real" login form (PS_OPENAPP)//
//              ://
//              :   <1> AppID to preselect//
//              :   <2> UserID to preselect//
//              :   <3> Primary boot flag//
//              :   <4> Template ID to use//
// ----------------------------------------------------------------------------//
**initLogin_OnOmniEvent_initLogin:**

    createParam = param1
    
    // Check to see that this system supports the EXAMPLES app//
   appIDs = .lst_AppIDs->list
    
    locate "EXAMPLES" in appIDs using @fm setting pos else
       errorText = "The EXAMPLES app cannot be found in this system"
       goSub errorMsg; errorText = ""
       call send_Event( @window, "CLOSE" )
       return
    end
      
    // Changing the appID and checking the "RunApp" checkbox will change //
    // the window title so something like "Open Application" or "Run //
    // Application", so cache it and reset it after the changes.//
    winText = @@window->text
   
    // Force the examples app to load//
    .lst_appIDs->changeText( "EXAMPLES" )
   
    // If the EXAMPLES app can be "Run" then the CHK_RUNAPP checkbox will be//
    // enabled - in this case we'll ensure it's checked.//
    if ( .chk_RunApp->enabled ) then
       .chk_RunApp->setChecked( TRUE$ )
    end
   
    // Restore the title from the template//
    @@window->text = winText
   
return

Once the user has entered their credentials, they may use the "Login" button control (LOGIN_BUTTON) to authenticate their request. The LOGIN_BUTTON control simply copies the entered Username and Password into the hidden EDL_USERNAME and EDL_PASSWORD controls and then executes the hidden BTN_OK's CLICK method to begin the process.

Here is the relevant code for the LOGIN_BUTTON CLICK event handler in the RTI_EXAMPLE_LOGIN_TEMPLATE commuter module:

/////
// loginButton_OnClick subroutine//
////
// CLICK event handler for the LOGIN_BUTTON control. //
////
//    1) Transfer the username and password entered by the user to the "real"//
//       controls (EDL_USERNAME) and (EDL_PASSWORD)//
//    2) Execute a Click method on the "real" OK button (BTK_OK) to log into//
//       the application.//
////
// ----------------------------------------------------------------------------//
**loginButton_OnClick:**

    // Transfer the credentials//
    .edl_UserName->text = .userName->text
    .edl_Password->text = .password->text
    
    // Click the OK button to authenticate//
    .btn_OK->click( "" )

return

This can be done on one of three ways:

• Use the "/TM" switch on the application command line.
• Use the "loginTemplate" element in the application's RXI file
• Enter the template name in the Application Settings dialog in the OpenInsight IDE.

(These options are shown in order of priority - command line switches override RXI file settings, which in turn overrides the Application Setting)

To set the login template form on the command line use the "/TM" switch and set the value to the template name like so:

C:\RevSoft\OpenInsight\Oinsight.exe /AP=EXAMPLES /TM=RTI_EXAMPLE_LOGIN_TEMPLATE

To set the login template form in an RXI file use the "loginTemplate" element and set its value to the template name, e.g:

<revPS appID="EXAMPLES">

<taskBarID>RevX.EXAMPLES_APP</taskBarID>

<bannerFile>examples_splashscreen.png</bannerFile>

<caption>Examples App</caption>

<showBanner>1</showBanner>

<showMonitor>0</showMonitor>

<noSpy>1</noSpy>

<hideEngine>1</hideEngine>

<elevate>0</elevate>

<minDisplaySecs>0</minDisplaySecs>

<loginTemplate>RTI_EXAMPLE_LOGIN_TEMPLATE</loginTemplate>

</revPS>

You may use the "Login Dialog Template" option in the Application Settings dialog to choose the template form like so:

Note: If you wish to override this setting you may use the "/TM" command line switch with a value of "!" to force PS_OPENAPP to load normally instead.

C:\RevSoft\OpenInsight\Oinsight.exe /AP=EXAMPLES /TM=!