new smartframe - looksoftware · 2012. 7. 24. · smartframe january 2010 page 3 of 30 getting...

Copyright © 2009 looksoftware Pty. Ltd. All Rights Reserved.

SmartFrame

The new face of your applications.

Introduction The looksoftware SmartFrame is designed to deliver the looksoftware SmartClient in a browser. The SmartFrame

wraps a web design around the looksoftware ActiveX SmartClient control. This approach provides for HTML

styling using CSS and a set of images for the web design. In conjunction with the newlook themes, images and

visual controls used for the refacing and repurposing of the original application, your IBM i business applications

can be delivered as a modern web application to your users.

The SmartFrame provides a skin capability, allowing you to customize to your specifications. The basic steps for

customization require that you build a set of custom images, edit the skin CSS styles, edit the supplied skin

scripts. With little effort, you can deliver a custom web application to suit your business graphical design and

user experience requirements. Some basic skins are available to showcase different web designs and provide

initial templates for your own web design.

To extend the design further, a plug-in capability has been included. Some basic plug-ins are available to allow

the user to swap SmartFrame skins and to resize the SmartFrame to suit each user. More information about the

initial plug-ins can be found in Appendix B of this document.

SmartFrame

January 2010 Page 2 of 30

Table of Contents Introduction ......................................................................................................................................... 1

Getting Started ..................................................................................................................................... 3

Customizing your SmartFrame ................................................................................................................ 4

First customization steps .................................................................................................................... 4

Next customization steps .................................................................................................................... 4

SmartFrame layout ................................................................................................................................ 5

Components Overview ........................................................................................................................... 7

SmartFrame ...................................................................................................................................... 7

Primary Skin...................................................................................................................................... 8

Secondary Skins................................................................................................................................. 9

SmartFrame entry parameters .............................................................................................................. 10

SmartFrame customization ................................................................................................................... 11

Style sheet ...................................................................................................................................... 11

Images ........................................................................................................................................... 12

Runtime script................................................................................................................................. 12

Configuration script ......................................................................................................................... 13

Supplied example SID........................................................................................................................... 24

The LookUI macro ............................................................................................................................ 24

SmartFrame plugins............................................................................................................................. 25

The SmartFrame plugin script ............................................................................................................ 25

Styling the SmartFrame plugin ........................................................................................................... 25

Activating the SmartFrame plugin ...................................................................................................... 26

Appendix A: Available skins................................................................................................................... 27

Appendix B: Available plug-ins............................................................................................................... 28

Appendix C: HideToolbars..................................................................................................................... 29

Appendix D: The @UI solution............................................................................................................... 30

SmartFrame


Getting Started It is assumed you have a newlook solutions folder installed, and for the purposes of this document, it is assumed

you will be installing the SmartFrame into your looksoftware developer environment. For example, your

solutions folder may be named @solution and may reside inside your :\Program Files\looksoftware 9.0

folder.

The frame, images and stylesheet you will install are the shipped defaults. Once you have the SmartFrame

installed and connected to your solution, you can start customizing the solution to suit your requirements.

Follow these steps to install the initial SmartFrame:

1. Unzip or copy the SmartFrame folder into your solution folder

The resulting folder should be similar to: c:\Program Files\looksoftware 9.0\@solution\SmartFrame

2. Merge the LookUI macro from the supplied UI.sid into your solution sid.

3. Edit the skinruntime.js script to use your solution

Open with Notepad: c:\Program Files\looksoftware 9.0\@solution\SmartFrame\skin\skinruntime.js

Modify the runtimeOptions variable

replace “-i@UI/UI.ini“ with your solutions ini path

4. Run the CreateDesktopIcons.vbs script to add an icon to your desktop

You can also manually create a desktop shortcut to the launch page: c:\Program Files\looksoftware 9.0\@solution\SmartFrame\SmartFrame.hta

(remember to set the shortcut to run Windows Minimized).

5. From your desktop, run the ‘looksoftware SmartFrame” icon

After installation, you can begin the customization process, and also use the SmartFrame to assist in the

development of your modernized application.

SmartFrame


Customizing your SmartFrame The Getting Started section allows you to see your modernized application inside the shipped SmartFrame with

the default styles, colors, images and sizing. To customize your SmartFrame beyond this initial step, there are

many settings to alter the default configuration to suit what you need. The detail of all the choices are outlined

in this document, however, you do not have to read all of it to begin the customization process.

First customization steps If you are satisfied with the sizing and location of the default SmartFrame, the first step is to change some colors

and images. Modify the skin style sheet, located in the skin\skin.css file to change colors. Edit each of the

images in the skin\images folder to suit your branding and themes. At this point, you should be able to

demonstrate an initial graphical modern application that suits your branding.

Next customization steps Beyond the basics, there are additional parameters to be set and customization to be performed. Using the skin

stylesheet, you can size, locate or hide any of the SmartFrame divisions. Using the primary skin runtime script

and the primary skin configuration script, you can set which function keys are displayed in the functions area,

which buttons and icons appear in the screen navigation and panel navigation divisions, and configure the

plugins that are to be included.

SmartFrame


SmartFrame layout The shipped layout contains eleven divisions - individual areas on the frame that can be manipulated with the

skin style sheets. Each area has a specific purpose and can be excluded, sized or placed in a specific location with

a simple change to the skin style sheets. The main container division contains the other ten divisions, and this

diagram identifies the shipped locations for those ten:

The purpose of each division is outlined here:

Body The body style in the style sheet is used for two main purposes. One is to define the alignment of the entire

container division, the other is to set the background color behind the container division.

ContainerDiv

This is the main division, and is designed to contain and display the other ten divisions. Its purpose is to set the

size of the area displayed to show your refacing and to set the border around that displayed area.

The size of this division is used to set the initial size of the launched SmartFrame window.

SmartFrame


HeaderDiv This division is designed to display the branding of your modernized application.

ScreenNavigationDiv

The purpose of this division is to display a set of icon buttons that apply to every screen in your application. For

example, an information button and a help button are typically displayed here. Buttons can specifically

represent a key from the currently displayed screen, and can be turned off or disabled when the currently

displayed screen does not support a specific function.

InformationDiv This division provides an area to display common information for the application. The shipped SmartFrame

supplies a means to identify the current signed on user, and the date and time they signed on.

FunctionsDiv

Designed to provide text buttons for some of the keys used for each individual screen, this division is shipped to

be displayed on the left, but occasionally is located at the bottom or at the right of the SmartFrame. The

capability to ignore keys from this area allows you to include a key as a button in the ScreenNavigationDiv or

PanelNavigationDiv, and not duplicate it in the FunctionsDiv.

GridLegendDiv

This division is shipped overlapping the bottom of the FunctionsDiv, and is designed to only appear when a grid

(subfile) is visible on the currently displayed screen. Its purpose is to provide additional information about what

grid options are available, and as such is only usable as a legend.

TitleDiv

The title for the currently displayed screen is placed and styled here. The title is also displayed in the window

title bar, where a prefix can be added for branding.

RuntimeDiv

Your refaced application is displayed in this division. It is important to ensure that the newlook scaling, color

theme and font choices are consistent with the styling of the SmartFrame.

PanelNavigationDiv This division provides a location designed to include back and forward navigation text buttons. Typically, F3, F12

and Enter are displayed here as navigation buttons, and are not displayed in the FunctionsDiv.

StatusDiv Any messages from the currently displayed screen are included and styled in this division.

FooterDiv This division is designed to provide additional branding and copyright of your modernized application. The skin

provides capability to add buttons or links here.

SmartFrame


Components Overview

SmartFrame The SmartFrame folder is normally stored within your Solution folder. It shipped with the folder named

SmartFrame - you can rename that folder if desired. Inside that folder are the complete set of files needed to

deliver your application using the SmartFrame. Those are:

SmartFrame.hta

SmartFrame.htm

UIcode.js

CreateDesktopIcon.vbs

skin folder/s

SmartFrame.hta This file provides the launch capability for the SmartFrame page. It is used to open a browser to individual

specifications, including the display of menu, toolbars and status bar.

SmartFrame.htm

This is the key to the SmartFrame. It contains a number of HTML DIVisions, which are used to style the web

design.

UIcode.js This file contains the JavaScript code used to run the SmartFrame and manage the plug-ins. It is normally not

necessary to modify this code.

CreateDesktopIcon.vbs The purpose of this VB script is to place an icon named “look SmartFrame” on your desktop, launching the

SmartFrame.hta to run in Windows Minimized mode, using the icon named skin.ico located in the primary skin

folder. It will typically be used by developers only, as the icons for end-user deployment will be created by the

installation process.

skin folder/s One or more of these folders will exist, containing the primary skin and any secondary skins for the SmartFrame.

The next two sections provide a description of the skins.

SmartFrame


Primary Skin Within the SmartFrame folder that resides inside your Solution folder, several skin folders can be located – each

containing a unique skin. It is currently required that the primary skin folder be named skin. Inside each skin

folder, these folders and files will reside:

images folder

skin.css

skin.hta

skin.ico

skin.js

skin.nlu

Skinruntime.js


images folder

All the necessary images for the primary skin are stored in this folder. The application refacing normally has its

own images folder directly inside the Solutions folder.

skin.css This is the style sheet for the primary skin contained in this folder.

skin.hta

This file provides the launch capability for the SmartFrame page using the primary skin contained in this folder. It

is used to open a browser to individual specifications, including the display of menu, toolbars and status bar.

skin.ico This icon is used to identify this skin for desktop shortcuts.

skin.js

When the SmartFrame starts, this javascript is run to set the configuration for the SmartFrame. It applies to the

primary and all secondary skins.

skin.nlu The NLU file provides the update instructions to the ActiveX control. The shipped NLU contains instructions to

use the currently registered ActiveX control, and points to the c:\program files\looksoftware 9.0 folder.

Skinruntime.js This javascript sets the runtime parameters for the ActiveX control. This script is where you set the pointer to

your solution, in order that the SmartFrame deploys your modernized application.


The purpose of this VB script is to place, or overwrite, an icon named “look SmartFrame” on your desktop,

launching the skin.hta to run in Windows Minimized mode, using the icon named skin.ico located in this skin

folder.. It will typically be used by developers only, as the icons for end-user deployment will be created by the

installation process.

SmartFrame


Secondary Skins Within the SmartFrame folder that resides inside your Solution folder, several additional skin folders can be

located – each containing a unique skin other than the primary skin. For consistency, these folders should be

named with a prefix of skin. Inside each skin folder, these folders and files will reside:

images folder

skin.css

skin.hta

skin.ico

An example of using secondary skins is where multiple SmartFrame sizes are required. Each secondary skin

contains a set of different sized stylesheet and images, and a plugin is configured to allow users to switch

between the included (primary and secondary) skins. Each skin could also be accessed by creating a desktop

shortcut to their own skin.hta file.

Another example of using secondary skins is where multiple SmartFrame themes are required. Each secondary

skin contains a set of different themed stylesheet and images.

images folder All the necessary images for this skin are stored in this folder. The application refacing normally has its own

images folder directly inside the Solutions folder.

skin.css This is the style sheet for this skin contained in this folder.

skin.hta This file provides the launch capability for the SmartFrame page using the skin contained in this folder. It is used

to open a browser to individual specifications, including the display of menu, toolbars and status bar.

skin.ico This icon is used to identify this skin for desktop shortcuts.

CreateDesktopIcon.vbs The purpose of this VB script is to place, or overwrite, an icon named “look SmartFrame” on your desktop,

launching the skin.hta to run in Windows Minimized mode, using the icon named skin.ico located in this skin

folder. This script will typically be used by developers only, as the icons for end-user deployment will be created

by the installation process.

SmartFrame


SmartFrame entry parameters The SmartFrame can be invoked from any other application by using the appropriate URL to launch or open. If

needed, you can use parameters on the URL string to send information to the SmartFrame. These parameters

can be sent to either of the SmartFrame.hta or the SmartFrame.htm files. There are three specific

parameters that can be used, and a generic means of receiving parameters and populating the newlook ActiveX

control with those values. The list of possible entry parameters is outlined here:

skin

o The name of the skin to use when the SmartFrame opens. This usually applies to one of the

secondary skin. If you omit this parameter, the next check is for a skin to match the current

Windows screen resolution (refer to the section about the Skin_InitializeScreenSizeStyles

function), and if that is not found, the primary skin is used when the SmartFrame opens.

o Example: file://c:\app_folder\@solution\SmartFrame\SmartFrame.hta?skin=skin800x600

startup

o The name of the macro to use on startup. This will override the name of the macro defined in

the skinruntime.js file.

o Example: file://c:\app_folder\@solution\SmartFrame\SmartFrame.hta?startup=Navigate2Menu

o To open the SmartFrame and prevent a startup macro from running, set this parameter to a

non-valid macro name.

o Example: file://c:\app_folder\@solution\SmartFrame\SmartFrame.hta?startup=Nothing

~name~

o If it is required to send entry parameters to the ActiveX control to be used with your refacing,

the SmartFrame can populate the ActiveX with the values of those parameters. In order for this

to be applied to the newlook ActiveX control, you must first define this variable to the

SmartFrame with the use of the Skin_SetEntryParameters function. This is defined in more detail

later in this document.

o Example: file://c:\app_folder\@solution\SmartFrame\SmartFrame.hta?user=ilook&pwd=ilook

o ..and: Skin_SetEntryParameters(“user”,”varUserName”);

Skin_SetEntryParameters(“pwd”,”varPassword”);

macro

o The name of the macro to run following the SetValue being performed for all other entry

parameter variables established with the Skin_SetEntryParameters function defined above. .

o Example: file://c:\app_folder\@solution\SmartFrame\SmartFrame.hta?macro=Navigate2Custome

r&CustomerNumber=12345

SmartFrame


SmartFrame customization To customize the SmartFrame for your specific requirements, there are several configuration tools. The skin

stylesheet named skin\skin.css and the images contained in your skin\images folder are the main ways to

apply your graphical design to the SmartFrame. Setting the pointer to your solution is done in the

skin\skinruntime.js script, along with the other ActiveX information. The main configuration for your

SmartFrame is done inside the skin\skin.js script.

Style sheet The SmartFrame body, every division, every button, every icon and all the SmartFrame text outside of the

runtime Division are styled, sized and positioned using the skin style sheet. Each skin will have its own skin.css

stylesheet in its particular skin folder.

The body has a style, which defines the background color outside the container – the default is grey, and the

alignment inside the browser – the default is centered.

Each division has its own style, prefixed with a # sign. The eleven styles are named:

#ContainerDiv

#HeaderDiv

#ScreenNavigationDiv

#InformationDiv

#FunctionsDiv

#GridLegendDiv

#TitleDiv

#RuntimeDiv

#PanelNavigationDiv

#StatusDiv

These divisions can be resized and relocated with their styles - using the top, left, width and height values. Note

that the ContainerDiv requires the position value to be relative, while the position for all the other divisions

needs to be absolute, and are defined as absolute within the ContainerDiv.

To hide a division, set the width and height values to zero. The SmartFrame will not include a division that is

ignored in this manner. This applies to the ten SmartFrame divisions within the ContainerDiv. An example is:

#InformationDiv {

width: 400px;

height: 30px;

visibility: visible;

}

All other styles are defined in the skin stylesheet for buttons, icons, text, etc. If you configure the use of any

custom styles in the skin initialization, they will not appear correctly unless a style is defined in the stylesheet for

each included skin.

SmartFrame


Images Each skin has an images folder, containing all the images referenced inside the skin stylesheet. If a style uses a

specific image, it should be contained in the images folder for all the skins included in your SmartFrame

configuration. As a general rule, all the styles and images contained in the primary skin should have a

corresponding style and image in each secondary skin.

Runtime script This script sets all the parameters for the ActiveX control which is placed inside the runtime division. Each

ActiveX parameter has a corresponding variable to be set inside the skin\skinruntime.js script. The newlook

ActiveX parameters are fully defined in the looksoftware IDE help, and this document contains only some of that

information. The main configuration parameters here are the runtimeOptions, runtimeCodeBaseCab and

runtimeVersion values.

Note that outside the skin stylesheet, the only other location for configuring SmartFrame colors is the

skin\skinruntime.js – where the BackColor, ForeColor and HoverColor values are set for the popup window

title and key bars. One very important note for the current version of the SmartFrame, is that the ForeColor for

the key bar in popup windows is determined by the ForeColor of the Key category definition inside the newlook

graphical color scheme.

The runtime initialization parameters are:

runtimeCodeBaseCab

o Defines the location of the newlook.cab

o If CODEBASE is not required, this can be omitted, or set to a null string value.

runtimeVersion

o Defines the current ActiveX control version number.

runtimeTakeFocus

o Determines if the ActiveX control will steal the focus from the HTML SmartFrame.

o Values: true or false (case sensitive)

runtimeTimeOut

o This property maintains the newlook ActiveX control session without disconnecting it if the user

navigates to another web page and back again.

runtimeHideToolbars

o Determines what toolbars will be displayed.

When used, the –h option in the runtimeOptions is ignored.

o Appendix C outlines the calculation of the runtimeHideToolbars value

runtimeHideConnectionDialog

o Determines if the Connection Dialog window will be hidden while connecting to the host server.


SmartFrame


runtimeUpdateFile

o Specifies the file that newlook's automatic updates tool is to reference to determine whether an

update is necessary.

runtimeOptions

o Specifies the command line parameters to run when the activeX control is started.

o Check the newlook help for "Command Line Arguments" for a detailed explanation.

runtimeStartupMacro

o Sets the –r value for the command line parameters.

o Is used to specifically set the Startup Macro rather than including it in the runtimeOptions.

runtimeBackColor

o Sets the background color of the activeX control frame.

runtimeForeColor

o Sets the foreground color of the activeX control frame text.

runtimeHoverColor

o Sets the color for the control foreground or text when mouse pointer over control.

runtimeErrorColor

o Sets the color for popup messages.

Configuration script The main configuration for your SmartFrame is done inside the skin\skin.js script. There is only one of these

for the SmartFrame, and that script resides in the primary skin folder. Inside the script, there are multiple

functions that can be configured for use with your SmartFrame. The functions that are available to modify the

configuration are:

Skin_Initialize

Skin_SetEntryParameters

Skin_AddPlugins

Skin_InitializePlugins

Skin_RemovePlugin

Skin_InitializeHTA

Skin_InitializeScreenSizeStyles

Skin_GetFunctionKeys

Event exit point functions

Within each of these functions, other functions can be invoked, or customized javascript can be written to

change the way the SmartFrame operates. All of these functions are outlined here:

SmartFrame


Skin_Initialize function

In this function, you can set variables to define how your SmartFrame will look, and invoke SmartFrame

functions to set the look and feel of your SmartFrame.

Variables:

functionHeaderText

o HTML code to appear for the functions division starting line.

functionShowNumber

o Show the function key number for each button in the function division.


functionShowNumberInHover

o Show the function key number in the hover text for each button button in the function division.


functionTextWidth

o Set the width the text in each button in the function division.

o For the complete full text, set this value to 0 (zero).

functionsForPopupsInFrame

o Sets whether the function keys are shown in any navigation division for popup windows.


o If set to false, when a popup is displayed, none of the buttons to activate a function key will be

active in any navigation division.

statusForPopupsInFrame

o Sets whether the status message is shown in the status division for popup windows.


addStatusToPopups

o Sets whether the status message is added to the popup window itself.


o This is a new control that contains the current message from the popup form.

The macro LookUI.PopupMessage is used to add the new control.

The value contained in the runtimeErrorColor variable is used to determine the text color of this

control, or the default value will be red.

titleForPopupsInFrame

o Sets whether the screen title is shown in the title division for popup windows.


SmartFrame


gridLegendForPopupsInFrame

o Sets whether the Grid Legend is shown in the Grid Legend division for popup windows.


gridLegendHeaderText

o HTML code to appear for the grid legend division starting line

gridLegendTextWidth

o Set the width the text in each option in the grid legend division.

o For the complete full text, set this value to 0 (zero).

titlePrefix

o This prefix will be displayed in the window title bar, followed by a space and the title for the

currently displayed screen.

Functions: This is the list of SmartFrame functions that can be run within the Skin_Initialize function to customize your

SmartFrame. Each of these has a specific purpose, but some are used only in conjunction with one of the others.

Since they are only establishing the configuration for future use, they can be run in any order.

IgnoreFunctionKey

ChangeFunctionKeyStyle

AddButtonToScreenNavigation

AddFunctionKeyToScreenNavigation

AddButtonToPanelNavigation

AddFunctionKeyToPanelNavigation

AddButtonToFooter

SmartFrame


The definition of each of these functions is here:

IgnoreKeyInFunctionsDivision For each refaced green screen, the SmartFrame will retrieve all the displayed Function Keys and add them to

the Functions division as a button. To ensure a Function Key is not shown in the Functions division, run this

javascript function in the Skin_Initialize function inside the skin customization script.

Syntax: IgnoreKeyInFunctionsDivision("key_name","key_text");

Example: IgnoreKeyInFunctionsDivision("F3","Exit");

ChangeFunctionKeyStyle

The default styles for the buttons in the Functions division are:

When button is on: clsFunctionButtonOn

When hovering over button: clsFunctionButtonHover

When Function Key is off: clsFunctionButtonOff

When Function Key is disabled: clsFunctionButtonDisabled

If a specific function key should use a different set of styles for these events, define those new styles in the

stylesheets for all skins, then run the ChangeFunctionKeyStyle function in the Skin_Initialize function inside

the skin customization script.

Syntax:

ChangeFunctionKeyStyle("key_name","key_text","buttonwhenON_classname","buttonwhenHOVER_classname",

"buttonwhenOFF_classname","buttonwhenDISABLED_classname");

Example: ChangeFunctionKeyStyle("F4","Prompt","clsPromptFunctionOn"," clsPromptFunctionHover","

clsPromptFunctionOff"," clsPromptFunctionDisabled");

AddButtonToScreenNavigation

To add an icon button to the ScreenNavigationDiv, run the AddButtonToScreenNavigation function in the

Skin_Initialize function inside the skin customization script. The button name can be used by other SmartFrame

functions, and it must be unique to your SmartFrame.

Syntax:

AddButtonToScreenNavigation("button_name","button_hovertext","function_to_invoke","button_on_classname

","button_hover_classname","button_off_classname");

Example:

AddButtonToScreenNavigation("btnRefresh","Refresh","SendActiveFunctionKey(this,'F5')","clsRefreshButtonOn",

"clsRefreshButtonHover","clsRefreshButtonOff");

SmartFrame


AddFunctionKeyToScreenNavigation

To affect an icon button added to the ScreenNavigationDiv with the AddButtonToScreenNavigation function,

run the AddFunctionKeyToScreenNavigation function in the Skin_Initialize function inside the skin

customization script. Identify the Function Key and its text, and reference the name of the button as one

defined in the AddButtonToScreenNavigation function. When this function is used, the impact on the icon

buttons in the Screen Navigation division will be to use the On, Hover and Off styles, based on whether the

Function key appears for each of the currently displayed screens.

Syntax: AddFunctionKeyToScreenNavigation("key_name","key_text","button_name_from_Screen_Navigation");

Example: AddFunctionKeyToScreenNavigation("F5","Refresh","btnRefresh");

AddButtonToPanelNavigation

To add an text button to the PanelNavigationDiv, run the AddButtonToPanelNavigation function in the

Skin_Initialize function inside the skin customization script. The button name can be used by other SmartFrame

functions, and it must be unique to your SmartFrame.

Syntax:

AddButtonToPanelNavigation("button_name","button_text","function_to_invoke","button_on_classname","butt

on_hover_classname","button_off_classname");

Example: AddButtonToPanelNavigation("pnlExit","Exit"

"SendActiveFunctionKey(this,'F3')","clsPanelButtonOn","clsPanelButtonHover","");

AddFunctionKeyToPanelNavigation To affect a text button added to the PanelNavigationDiv with the AddButtonToPanelNavigation function, run

the AddFunctionKeyToPanelNavigation function in the Skin_Initialize function inside the skin customization

script. Identify the Function Key and its text, and reference the name of the button as one defined in the

AddButtonToPanelNavigation function. When this function is used, the impact on the icon buttons in the Panel

Navigation division will be to use the On, Hover and Off styles, based on whether the Function key appears for

each of the currently displayed screens.

Syntax:

AddButtonToPanelNavigation("button_name","button_text","function_to_invoke","button_on_classname","butt

on_hover_classname","button_off_classname");

Example:

AddButtonToPanelNavigation("pnlExit","Exit","SendActiveFunctionKey(this,'F3')","clsPanelButtonOn","clsPanelB

uttonHover","");

SmartFrame


AddButtonToFooter

To add a picture button to the FooterDiv, run the AddButtonToFooterfunction in the Skin_Initialize function

inside the skin customization script. The button name can be used by other SmartFrame functions, and it must

be unique to your SmartFrame.

Syntax:

AddButtonToFooter("button_name","button_hover_text","function_to_invoke","button_classname","button_ho

ver_classname");

Example: AddButtonToFooter("ftrPoweredBy", "Powered by looksoftware suite of modernization tools",

"RunMacro('LookUI.looksoftware')", "clsPoweredBy", "");

More SmartFrame functions

Additional SmartFrame functions are available for use with the newlook ActiveX control with your skins and your

plugins. The shipped functions are:

RunMacro

SetValue

GetValue

SendKeys

SendFunctionKey

SendFunctionKeyWait

SendActiveFunctionKey

Some of these SmartFrame functions require support with macros or variables in your solution SID. All of them

are outlined here:

RunMacro(newlook_macro) Runs the newlook macro specified by name.

SetValue(item, value) Sets an item (a newlook variable or property of a newlook object) to the specified value.

GetValue(item, defaultvalue) Retrieves value of item (a newlook variable or property of a newlook object).

SendKeys(keys) Sends the keystroke specified to the newlook ActiveX control.

SendFunctionKey(key)

Sends the named Function Key to the newlook ActiveX control.

SendFunctionKeyWait(key) Sends the named function key to the newlook ActiveX control with the WAIT parameter set to *YES.

SendActiveFunctionKey(this, key) Sends the named function key to the newlook ActiveX control if the button, to which this macro is connected,

is currently activated.

SmartFrame


Skin_SetEntryParameters If it is required to send entry parameters to the ActiveX control to be used with your refacing, the SmartFrame

can populate the ActiveX with the values of those parameters. These parameters can be sent to either of the

SmartFrame.hta or the SmartFrame.htm files, and can be transferred by defining them with the

Skin_SetEntryParameters function in the skin.js script.

Syntax: SetEntryParameter("URL_variable_name",""newlook_variable_name");

Example: SetEntryParameter("user",""varUserName");

Skin_InitializeHTA

This function is used to set the parameters to define the appearance of the SmartFrame window as it is

launched from the SmartFrame.hta file.

launchStatus

o Values: “yes” or “no”

o Shows or hides the status bar at the bottom of the IE browser window.

launchToolbar


o Shows or hides the standard IE browser toolbar, with buttons such as Back and Forward.

launchLocation = "no";


o Shows or hides the IW browser location entry field where you enter the URL.

launchMenubar = "no";


o Shows or hides the menu bar of the IE browser window.

launchDirectories = "no";


o Shows or hides the standard IE browser directory buttons, such as What's New and What's

Cool.

launchResizable = "yes"


o Allows or disallows the user from resizing the IE browser window.

launchScrollbars = "yes";


o Shows or hides the scrollbars if the document is bigger than the IE browser window.

SmartFrame


Skin_AddPlugins

This function is to used to instantiate a SmartFrame plugin. There must be a matching plugin javascript (for

naming rules, see the SmartFrame Plugin section later in this document), and the Skin_AddPlugins function will

attach that script to the SmartFrame, and create a special plugin division in the SmartFrame, located to match

the plugin style.

To add a specific plugin, run the AddPlugin function from inside the Skin_AddPlugins function.

Syntax: AddPlugin("plugin_name");

Example: AddPlugin("SkinChooser");

More information on using SmartFrame Plugins is found in a later section in this document.

Skin_InitializePlugins This function is to used to run a specific initialization script for an individual SmartFrame plugin. This is an

optional function, and is only required if the plugin needs an initialization process.

To initialize for a specific plugin, run the plugin’s own initialization function from inside the Skin_InitializePlugins

function.

Example: Plugin_InitializeSkinChooser();


Skin_RemovePlugin

This function is to used to remove a SmartFrame plugin. This is an optional function, and would likely be used if

one plugin replaces another, and the first should be removed. The Skin_RemovePlugin will detach the

SmartFrame plugin script and remove the SmartFrame plugin division from the SmartFrame.

To remove a specific plugin, run the RemovePlugin function from inside the Skin_RemovePlugins function.

Syntax: RemovePlugin("plugin_name");

Example: RemovePlugin("SkinChooser");


SmartFrame


Skin_InitializeScreenSizeStyles

The primary skin typically works well at only one or two Windows screen resolutions. If you have secondary

skins to handle other Windows screen resolutions, the SmartFrame can open with a different skin, depending on

the resolution of the Windows desktop.

To do this, the Skin_ InitializeScreenSizeStyles function can set a different skin for up to ten different Windows

resolutions. To recognize a screen resolution setting, each of the ten resolutions has been given a numeric

identifier. Those identifiers and their matching resolutions are:

0 = 640 x 480

1 = 800 x 600

2 = 1024 x 768

3 = 1152 x 864

4 = 1280 x 960

5 = 1400 x 1050

6 = 1600 x 1200

7 = 1920 x 1440

8 = 2048 x 1536

9 = 2560 x 1920

If a specific Windows screen resolution is not included in this function, the default is the primary skin – which

resides in the folder named skin.

Syntax: SetScreenSize(Resolution_identifier, "resolution_skin_folder");

Example: SetScreenSize(1,"skin800x600");

SetScreenSize(3,"skin1152x864");

SmartFrame


Skin_GetFunctionKeys

The SmartFrame will retrieve all the function keys for each currently displayed screen, and then build the

appropriate buttons into the FunctionsDiv, the ScreenNavigationDiv or the PanelNavigationDiv. The default is to

retrieve the set of keys from the App.ActiveForm.Functions array from inside the newlook ActiveX control. This

can be overridden if you have soft-coded the function keys inside your solution.

The Skin_GetFunctionKeys function can be used retrieved a string containing a delimited set of function key

values and their related text. It is invoked on each of the OnReceive, OnRefresh, and OnOpen events from the

newlook ActiveX control.

Three variables are set in the Skin_GetFunctionKeys function inside the skin.js script. They are outlined here:

functionKeysNumbered

o Values: true or false (defaults to false, case sensitive)

o This flag identifies if the function keys are named or identified by their ASCII number.

functionKeysDelimiter

o Values: string (defaults to ";")

o the delimiter in the function key string

functionKeysText

o Values: string (defaults to "")

o The string containing a delimited array of the function keys for the current screen.

Syntax of the function key string:

- with functionKeysNumbered = false: "Enter=OK;Fn=xxxxxxx;Fn=xxxxxx;"

- with functionKeysNumbered = true: "13=OK;999=xxxxxxx;99=xxxxxx;"

Example: functionKeysDelimiter = ";”;

functionKeysText = GetValue(“functionKeyText”;””);

functionKeysNumbered = false;

SmartFrame


Event exit points

For every event that can occur with the newlook ActiveX control, the SmartFrame performs the necessary

processing, then invokes an Exit point function for that event. This allows further customization of your

modernized application using the SmartFrame. All available newlook ActiveX events have their own exit point,

and these functions are identified here.

Skin_OnClosed

o This exit point fires when an added form is Closed.

Skin_OnConnectStateChanged

o This exit point fires when the connection status has changed from Connect to Disconnect or

vice-versa.

Skin_OnFunctionKeyChanged

o This exit point fires when the AppActiveForm.Functions array has changed.

Skin_OnOpened

o This exit point fires when an added form is Opened.

Skin_OnReceived

o This exit point fires when a host form is received.

Skin_OnRefreshed

o This exit point fires when a host form is received a second or subsequent time in succession.

Skin_OnSent

o This exit point fires when the host form is sent back to the host with a function key.

Skin_OnStatusChanged

o This exit point fires when the App.ActiveForm.Message has changed.

Skin_OnTitleChanged

o This exit point fires when App.ActiveForm.Title has changed.

Skin_OnViewChanged

o This exit point fires when a user swaps between Emulator view to GUI view or vice versa.

Two other special exit points are available. They are outlined here:

Skin_AllEvents

o This exit point fires whenever ANY event occurs.

Skin_OnSwapSkin

o This exit point fires any time a skin is swapped inside the SmartFrame. These usually occur from

within a plugin More information on using SmartFrame Plugins is found in a later section in this

document.

SmartFrame


Supplied example SID An example shared repository is included with the SmartFrame and is named UI.sid. This file is provided only as

a template and contains a macro - named LookUI - that is required in your Solution repository (your SID file) to

perform the necessary functions for the SmartFrame.

The LookUI macro The LookUI macro is used to communicate between the SmartFrame and the newlook ActiveX control. In

addition to providing the basics, several additional functions are available. Those are outlined here:

1. If you want the HTML frame closed, follow these steps inside your solution SID.

a. Set the variable varExitRequested to True (not case sensitive)

b. Trigger an event in the browser- you can manually make this happen by running the macro LookUI.TriggerEvent

2. If you want the current signed on user information displayed in the header, follow these steps inside your

solution SID:

a. Run the macro named LookUI.SignonOnReceive on the Sign on screen OnReceive event

b. Run the macro named LookUI.SignonOnRefresh on the Sign on screen OnRefresh event

c. Run the macro named LookUI.SignonOnSend on the Sign on screen OnSend event

d. On the Sign on screen, fill the variable varUserName with the currently Signed on user

3. If you want to use the Grid Options Legend, follow these steps inside your solution SID:

a. Run the macro named LookUI.GridCheck on the App OnReceive event

b. Run the macro named LookUI.GridCheck on the App OnRefresh event

4. If you want to use the Information button with the SmartFrame, follow these steps inside your solution SID:

a. Create a new macro named Information to display support information.

SmartFrame


SmartFrame plugins To extend the functionality of the SmartFrame, the plugin functionality can be used. This allows you to write

your own javascript code and additional styles to affect the look and/or feel of the SmartFrame.

There are three components to every SmartFrame plugin. First, an individual plugin javascript is required to

perform the additional functions. Second, the plugin must be added to the SmartFrame with the use of the skin

configuration script in the skin.js file. Third, a style for the plugin and any additional styles, and these are

defined in the skin stylesheet in the skin.css file.

The SmartFrame plugin script The plugin script is responsible for all the processing required by the SmartFrame plugin. This script resides in

the primary skin folder, and should be named with a prefix of plugin and a suffix of .js . The rest of the script

name is used as the name of the plugin.

Example: pluginSkinChooser.js is the script for the SkinChooser SmartFrame plugin.

The first function inside the SmartFrame plugin script can be the Initialization routine for the plugin. The

initialization function is run from inside the Skin_InitializePlugins function in the skin configuration script.

Styling the SmartFrame plugin A style is required for the SmartFrame plugin division that is created when the plugin is activated. This style must

reside in all the primary and secondary skin stylesheets in their skin.css file. The division should be named with

a prefix of #plugin and a suffix of Div and the rest of the style name is the name of the plugin.

Example: #pluginSkinChooserDiv is the style used for the SkinChooser SmartFrame plugin.

If the SmartFrame plugin will not have any visible components to display on the SmartFrame, the division style is

still required. If it needs to be hidden, style the division in the same manner as the clsHiddenDiv style. An

example of a hidden SmartFrame plugin division style is here:

#pluginCollectStatisticsDiv {

width: 0px;

height: 0px;

visibility: hidden;

}

Any additional styles used for the SmartFrame plugin, or components to be displayed on the plugin division, are

added to the primary and secondary skin stylesheets in their skin.css file.

SmartFrame


Activating the SmartFrame plugin For each SmartFrame plugin, the plugin script needs to be attached to the SmartFrame, and the plugin division

needs to be created. When the skin configuration script is run as the SmartFrame is started, the AddPlugin

function needs to be invoked inside the Skin_AddPlugins function in the skin configuration script. Information

related to Skin_AddPlugins is found in an earlier section in this document.

Typically, a SmartFrame plugin will be activated to show information or buttons on the SmartFrame. Some

plugins use the Event Exit points to process specific plugin functions. For example, if a plugin wanted to collect

information from the currently displayed screen, the Event Exit points named Skin_OnReceived and

Skin_OnRefreshed would include a call to one of the SmartFrame plugin javascript functions to collect that

information.

All of the plugins have access to the SmartFrame internal functions. The earlier section in the document titled

‘More SmartFrame functions’ includes a definition of these internal functions. The most common internal

functions used by SmartFrame plugins are:

RunMacro – run a newlook macro.

GetValue – retrieve a variable or property value from the newlook ActiveX control.

SetValue - set a variable or property value from the newlook ActiveX control.

The best way to learn about SmartFrame plugins is to review the script, styles and skin configuration for an

existing plugin. The shipped SmartFrame plugins are detailed further in Appendix B: Available plug-ins.

SmartFrame


Appendix A: Available skins The SmartFrame is shipped with a default primary skin that can be used as a basis for your own customization. If

you would like examples of stylesheets and images for more skins, a selection is also shipped for you to start

with.

Each of the shipped skin folders contains only the stylesheet in the file named skin.css and the images folder

to match that skin. The shipped skin examples are outlined here:

skin

This is the default skin set to a base size to fit on a 1024x768 screen, and has a standard set of images to match

the style identified in the SmartFrame layout as outlined in a section earlier in this document.

skin640x480 This skin matches the default skin layout, but is set to fit on a 640x480 screen.




skinright

This skin is similar to the default skin layout, set to fit on a 1024x768 screen, with the functions and grid legend

divisions aligned to the right of the SmartFrame.

SmartFrame


Appendix B: Available plug-ins The SmartFrame is shipped with some plugin examples for you to install, or use as a basis for creating your own

SmartFrame plugins.

For each of the shipped SmartFrame plugins, three files are included:

The SmartFrame plugin script

A basic skin stylesheet – skin.css

A basic skin configuration script – skin.js

Some plugins will use the ability to swap between primary and secondary skins, and those skin folders must also

be included in your SmartFrame deployment.

The shipped SmartFrame plugin examples are outlined here:

FrameSize

This plugin supplies the ability to swap between differently sized skins. It displays two buttons, one that will

swap the skin to a smaller sized skin, the other to swap the skin to a larger sized skin. In the shipped version,

there are five different sized skins, starting at 640x480 and sizing up to 1280x960.

FrameSize2 This plugin supplies the ability to swap between two differently sized skins. It displays one button, which will

swap the skin to the other sized skin. In the shipped version, the two skins are sized at 1024x768 and 1152x864.

SkinChooser This plugin adds a button to the SmartFrame screen navigation division to choose a different skin than the

currently displayed SmartFrame skin. When that button is clicked, a number of other buttons appear that can be

used to swap the skin. This SmartFrame plugin is useful for providing alternate choices of colors and graphic or

icon themes to the end-users.

Note, swapping skins does not impact the graphical scheme shipped with your solution, and this should be taken

into account when you are building multiple designs of the SmartFrame for deployment.

AddSkinIcon This plugin supplies the ability for the user to add a shortcut to the desktop that will start the SmartFrame

configured to the current skin. A button is displayed on the SmartFrame, and if clicked, the user will be asked to

name their desktop shortcut before that shortcut is created.

Note: any existing desktop shortcut named the same will be overwritten.

This plugin uses a newlook script to add the shortcuts to the desktop. It is named LookUIicons, and is included

in the supplied UI.sid.

SmartFrame


Appendix C: HideToolbars When defining the ActiveX runtime properties, the HideToolbars parameter allows the showing or hiding of the

following toolbars.

Title bar

Menu bar

Function Key

Status bar

The calculation of the value for the HideToolbars property is as follows:

Absolute values All toolbars -1

None (in full and pop-up) 0 Cumulative values Title bar only (in full screen and pop-up) 1

Menu bar only (in full and pop-up) 2 Function Key bar only (in full screen and pop-up) 32

Status bar only (in full screen and pop-up) 64 Title (full screen only) 128 Menu (full screen only) 256

Function Keys (full screen only) 512 Status (full screen only) 1024

The value for the HideToolbars property will be either -1, 0 or the sum of several of the Cumulative values. For

example, if you want to show the Title bar and the Function keys in the popup only, then you would add these

values to get 706:

Menu bar only (in full and pop-up) 2 Status bar only (in full screen and pop-up) 64 Title (full screen only) 128

Function Keys (full screen only) 512 HideToolbars value: 706

SmartFrame


Appendix D: The @UI solution For an example of how the SmartFrame is used, you can obtain the @UI solution. This is a newlook refaced

solution that is delivered with several batch 5250 files that can be used offline as a demonstration of the basics

of the newlook development suite.

The contents of the @UI folder are outlined here:

@UI – the solution folder

UI.ini - settings

UI.nlg - graphical scheme

UI.nlh - emulator scheme

UI.nlk - keyboard scheme

UI.sid - shared rules repository

(includes the LookUI and LookUIicons macros)

UIUser.sid - user repository

SmartFrame - contains the default SmartFrame

demo - contains all the 5250 offline nl files

images - contains the default images for the solution

new smartframe - looksoftware · 2012. 7. 24. · smartframe january 2010 page 3 of 30 getting...

Documents