Spin Edit

axSpinEdit

Description

Use this extension to add a spin edit box into a 5250 screen. The end-user can use this extension to change a field value by scrolling a list of enumerated values. This is an extended Dropdown element.

Usability

Context	Supported
Input screen fields	Yes
Output screen fields	Yes
Input subfile fields	Yes
Output subfile fields	Yes
New screen elements	Yes

Properties

Name	Description and Comments	JavaScript	Shipped default
style	CSS to apply to the element	Yes. Must return a valid style object.	Blank
dataSourceType	Indicates where the source data is obtained from.	No	fixedValues
visibleLines	Indicates the number of visible lines. When a selected value is greater than 1, the element acts as a spin edit element. When the value is 1, it will behave as a drop down element.	No	2
multipleSelect	Allows selection of multiple data or single data.	No	false
lowerRange	The lowest value in the element list.	No	Blank
upperRange	The highest value in the element list.	No	Blank
tableName	For Static Table data source type, this must be the value set for the name = property.	No	Blank
onFillDropDown	Script codes to execute during the filling up of element list.	Yes	Blank (i.e. no script to execute – interpreted as ROW.text)
xmlFileName	Name of XML file when the source type is XML.	No	Blank
xmlFileLocation	Path to locate the xmlFileName when the source type is XML.	No	*DEFAULT which is equal to /ts/screens/<private folder>
fixedValues	For Fixed values data source type, you must enter the pair of data values that will appear on the element list.	Yes. Must retun an array of value pair object.	No
additionalEntries	Use this property to add one or more entries to the spin edit element. Note that if you use this option with static tables, dynamic tables or XML documents, the values you are adding are inserted into the underpinning table – which subsequently causes them to appear element list. This may impact other eXtensions or scripting that also use the same underpinning table.	Yes	No
onSelectValue	Data to be displayed as a result of the script code execution during the selection of value.	Yes	Blank (i.e. no script to execute – interpreted as ROW.value)
onSelectedValueChanged	Script code to execute when the current value has changed.	Yes	FIELD.setValue(ROW.value)
sqlQueryName	For Dynamic Table data source type the value set for the name = property	No	Blank
sqlVariables	For Dynamic Table data source the variables used in your query.		ENV.SQL.SQLVariableLibrary = USERENV.dftSQLDataLibrary
enabled	Indicates whether this element is enabled. TS2 only.	Yes. Must return a Boolean.	True

Notes, Comments and Warnings

dataSourceType:

Determines the method used to populate the element. The options are:

Fixed Values: use this setting for a small number of values and the values don't change.

Static Table: static tables are loaded once from the server at start up. The name of the static table must be the name specified in tableName.

Static tables are very efficient and they can contain hard coded values or can be loaded by executing SQL commands.

XML File: the data to fill the table is obtained from an XML file located by default in /ts/screens/<private folder>. To specify another location change the xmlFileLocation property.

Dynamic Table: use this option carefully as it is the only one where the data is loaded at every screen arrival with an expected performance impact in the rendering of the screen. When you use this option you must specify the name of the query in sqlQueryName as defined in your dynamic tables file.

This value indicates that the data should come from a dynamically created table.

· A dynamic table is (re)loaded every time a screen is displayed.

· Dynamic tables are expensive to use compared to static tables.

· Only usethem whenthe table content needs to vary according tosome dynamic criteria (eg: current company, current product, etc).

· Dynamic tables can only be loaded by SQL commands.

You can use the keepLastKey option to improve performance, if multiple requests using the same query key are commonly made.

Should I use a Static or a Dynamic Table?

You do not have to use a dynamic table just because you want to execute an SQL command to load the table. You can load static tables from SQL commands as well.

You can usethe highly efficient static tables inways you may not know about.

Imagine a scenario where a currency table’s content needs to change according to a company number (ie: You can only use certain currencies for certain companies).

Your immediate reaction may be to just use a dynamic table - passing the company number as an SQL variable to control which currencies are selected by the SQL command that is executed to fill the dynamic table.

This will work, but compared to using a static table this approach is expensive to execute.

You can improve this approach in several ways by using static tables instead:

Option 1: Create a single Static Table named Currency:

It would contain all the currency details for all the companies - and the associated company number as an extra column. When filling the element list, you can use scripting in the onFillDropDown property to omit table entries that are not valid for the current company by returning ENV.returnValue as null (meaning novisible entry is to be added to the element list).

Option 2: Create multiple Static Tables named Currency_CC:

Where _CC is the company number (say).

Script the element’s tableName property to dynamically change.

You are using static tables - butnow you are dynamically changing the table name - instead of the table content.

Note: This approach also works well with XML sourced tables. For example, you could also create an RPG program that runs every night (say).

It would read corporate "static" data files and flatten them out into a highly structured series of XML documents - where the name of the document (ie: table) is meaningful.

Option 3: Usestart upor log on logic to load the"correct" set of static table data

When there is a clear point in the application where the user logs on and selects a company to work with - you canscript an onArrive or onLeave events to force all static tables to load or reload.

Where they are loaded from SQL you can pass variables to the SQL executed to load them (eg: theselected company number).

Now the static table Currencywould only ever contain the currencies for the currently selected company.

All the "users" of the Currency static table - like drop downs - no longer have to worry about the content - it will always be correct for the currently selected company.

What is a ROW?

The element list makes use of the aXes table structures. It means that the data to populate the list is stored in memory in a table-like structure consisting of rows and columns. For example, consider a table defined like this:

DefineObjectInstance { className = "StaticTable",

name = "Gender",

source = "inline",

rows = {

{value="M",text="Male"},

{value="F",text="Female"},

},

};

(Note that for such a table you would most likely set the dataSourceType to Fixed Values and type in the values manually).

At start up aXes populates the tables with one called Gender. It will have 2 rows, each ROW consisting of columns value and text. Using the Gender table, ROW.value would yield the current row's value= value and ROW.text the current row's text= value.

There is no constraint on how you name the row columns. If you use other names you must remember to change the default values to reflect the column names.

For example, if your file or fixed values define your columns like this:

rows = {

{codigo="M",descripcion="Masculino"},

{codigo="F",descripcion="Femenino"},

},

};

The default values or script code should refer to ROW.codigo and ROW.descripcion.

onFillDropDown event:

This event populates the element list. It will fire (following our table example) whenever a screen (any screen) that has the element whose tableName was set to Gender arrives.

It will locate the Gender table and iterate through all its entries.

For each entry it will add an entry where the visible text in the list is equal to the value in text column of the Gender table. The result in our example will be a spin edit element with 2 entries: Male and Female.

This is the simplest way to use onFillDropDown.

A more powerful way would be to fill the list with a value resulting from the evaluation of a more complex expression.

If we extended the Gender table like this:

DefineObjectInstance { className = "StaticTable",

name = "Gender",

source = "inline",

rows = {

{value="M1",text="Male", agerange="16-25"},

{value="M2",text="Male", agerange="26-35"},

{value="M3",text="Male", agerange="36-45"},

{value="F1",text="Female", agerange="16-25"},

{value="F2",text="Female", agerange="26-35"},

{value="F3",text="Female", agerange="36-45"},

},

};

We could change onFillDropDown to say:

ROW.text + "s aged " + ROW.agerange

The element list would end up with entries that look like this:

Males aged 16-25

Males aged 26-35

Males aged 36-45

Females aged 16-25

Females aged 26-35

Females aged 36-45

Note that executing custom code is a relatively expensive process. This event is fired once for each entry in the element list. If you have a lot spin edit elements and/or large lists this can have an impact on screen rendering time. The eXtension recognises the special case of an empty script (the default) and returns the value of ROW.text without having to execute any custom code. Consider carefully if you need to use this event, or if you can change the structure of your table so that ROW.text already contains the correct data.

onSelectValue event:

The code in this event determines what entry in the element list to set as the selected. It can be something simple like:

ROW.value

If the expression does not return a value of type Boolean, the default logic of comparing the value is returned with the associated field's value.

An example of an expression returning a value of type Boolean would be:

(ROW.value == "Hello")

Note that executing custom code is a relatively expensive process. This event is fired once for each entry in the list. If you have a lot spin edit elements and/or large lists, this can have an impact on screen rendering time. The eXtension recognises the special case of an empty script (the default) and returns the value of ROW.value without having to execute any custom code. Consider carefully if you need to use this, or if you can change the structure of your table to avoid it.

onSelectValueChanged event:

This event fires when the current element value changes. The default behaviour here is

FIELD.setValue(ROW.value)

In other words, set the value of the field (which is referred to as FIELD) associated with the element list to the value of the selected ROW.

additionalEntries:

Lets you add entries in addition to those added by the specified method in dataSourceType.

The easiest and preferred way of adding a blank entry at the top of the element list would be to add it to your static table or fixed values with blank values.

Another way would be to use additionalEntries.

This property works by calling an internal method named addTableROW. It receives 2 parameters:

oRow	Object - represents the ROW. It must be structurally the same as any of your other ROWs. In other words it must have the same properties.
bAtBegin	Boolean - Indicates whether to add the entry at the beginning or at the end of the element list. Defaults to false

For example, to add an entry at the top of the element list source by the Gender table you would this in your additionalEntries property:

var oGenderROW = {value: "", text: "Select an entry from this list", agerange:"" }

this.addTableROW(oGenderROW, true); /* Note the this qualifier */

Note that when the list is associated to a field, the field will be set to the

"" when this entry is selected unless you add logic to the onSelectValue and onSelectValueChanged.

fixedValues:

Sets the data of Spin Edit when Fixed Values is selected as the dataSourceType. If using script, the ENV.returnValue must contain an array of value pair object as follows:

ENV.returnValue = [ { value: "GA", text: "Georgia" },

{ value: "HI", text: "Hawaii" },

{ value: "UT", text: "Utah" }

];

In Application, appStylesTheme property = JQueryUI

When JQueryUI is selected from Application->Styling->appStylesTheme property, the display will change according to the theme that was set in the Application’s jqueryTheme property. Basically, the default border and the font styles will be based on the JQuery theme.

In addition, using the JQuery extension version, the Spin Edit’s behaviour changed to properly support the visibleLines property. Using the basic extension, setting the visibleLines property to greater than 1 will have no effect on the height of the extension. The basic extension’s height will always be the same as the height of the field. For the JQuery extension, setting the visibleLines property to more than 1 will automatically resize the height of the extension so that the number of items indicated in the visibleLines property will be visible. To support the original basic extension’s behaviour of the height being always the same as the field, setting the visibleLines property to 0 will make the JQuery extension behave like this.

Basic extension with visibleLines set to 4.

JQuery extension with visibleLines set to 4.

visibleLines:

In Chrome and Safari, this attribute may not work as expected for values 2 and 3. In mobile, there is no spin edit so only a normal dropdown will be displayed whatever the value of this property is.

In Application, appStylesTheme property = Material Design

When Material Design is selected from Application->Styling->appStylesTheme property, the display will change according to the theme that was set in the Application’s mdTheme property.

Material Design extension with visibleLines set to 4.

Administrators

Legal Mentions

aXes is brought to you by:

Serving the IBM i community for 30 years.