Videos

				

var obj = {dialog.object}.getControl('EXPANDINGMENU1');
var data = {
	items:[
		{
			html: 'Category 1', 
			value: 'category1',
			icon: 'svgIcon=#alpha-icon-addCircleBorder:icon,24',
			action: '',
			children: [
				{
					html: 'Action 1', 
					value: 'action1',
					action: 'action:1',
					icon: 'svgIcon=#alpha-icon-bandAidCrossed:icon,24'
				},
				{
					html: 'Action 2', 
					value: 'action2',
					action: 'action:2',
					icon: 'svgIcon=#alpha-icon-bellRing:icon,24'
				}
			]
		},
		{
			html: 'Category 2',
			value: 'category2',
			action: '',
			icon: 'svgIcon=#alpha-icon-heartSolid:icon,24',
			children: [
				{
					html: 'Action 4', 
					value: 'action4',
					action: '',
					icon: 'svgIcon=#alpha-icon-map:icon,24',
					children: [
						{
							html: 'Action 4a', 
							value: 'action4a',
							action: 'action:4a',
							icon: 'svgIcon=#alpha-icon-trendingDown:icon,24'
						},
						{
							html: 'Action 4b', 
							value: 'action4b',
							action: 'action:4b',
							icon: 'svgIcon=#alpha-icon-trendingDown:icon,24'
						}
					]
				},
				{
					html: 'Action 5', 
					value: 'action5',
					action: 'action:5',
					icon: 'svgIcon=#alpha-icon-trendingDown:icon,24'
				}
			]
		},
		{
			html: 'Category 3', 
			value: 'category3',
			action: '',
			icon: 'svgIcon=#alpha-icon-shield:icon,24',
			children: [
				{
					html: 'Action 7', 
					value: 'action7',
					action: 'action:7',
					icon: 'svgIcon=#alpha-icon-shuffle:icon,24'
				}
			]
		}	],
	actions: {
		action: function(arg){
			alert('Action' + arg);
		}
	}
}
{dialog.object}.populateExpandingMenuControl('EXPANDINGMENU1',data);
					
		

JSON_shred() Function - This function has been enhanced. The input schema that describes how the JSON should be shredded is now optional. Also, the function can automatically inject linking values into the JSON if the JSON does not already have appropriate linking values. If the input schema is not specified then linking values are automatically injected.

The purpose of the JSON_shred() function is to take a complex JSON document (with one or more nested arrays) and decompose the JSON into multiple flat arrays, none of which have nested arrays.

The new syntax for the function is:

 C result =  JSON_shred(C json [,C schema [,C topArrayName [,L flagAddSurrogatePrimaryKey [,C surrogateKeyName ]]]])

Where:

• json - json document to shred
• schema - optional schema that defines how the JSON document should be shredded
• topArrayName - optional. The name of the top level array - if not specified '__top' is used
• flagAddSurrogatePrimaryKey - if .t. then linking key values are injected into the JSON data. The linking values are GUIDS. If the schema is not specified, this parameter is automatically set to .t.
• surrogateKeyName - defaults to '__surrogatePrimaryKey'. The name of the field that contains the linking value.

Example:

dim json as c 
json  = <<%str%
[
    {"Firstname": "John", "Lastname" : "Smith", "City" : "Boston", "State" : "MA", "Children": [
        {"Name" : "Callie", "Age" : 5},
        {"Name" : "Griffin", "Age" :3},
        {"Name" : "Luke", "Age" : 1}
        ]
    }, 
    {"Firstname": "Henry", "Lastname" : "Rhodes", "City" : "New York", "State" : "NY", "Children": [
        {"Name" : "Howard", "Age" : 15},
        {"Name" : "Robert", "Age" : 11}
        ]
    }
]

?json_shred(json)

{
    "__top": [
        {
            "__surrogatePrimaryKey": "475750b196554658b2518fde4bfaec6e",
            "Firstname": "John",
            "Lastname": "Smith",
            "City": "Boston",
            "State": "MA"
        },
        {
            "__surrogatePrimaryKey": "c970381d48aa4abfa92d0f46d02ead27",
            "Firstname": "Henry",
            "Lastname": "Rhodes",
            "City": "New York",
            "State": "NY"
        }
    ],
    "Children": [
        {
            "ParentLinkingValue": "475750b196554658b2518fde4bfaec6e",
            "LinkFieldName": "__surrogatePrimaryKey",
            "__surrogatePrimaryKey": "16963be3261c4d82a50152dfb18f9ff0",
            "Name": "Callie",
            "Age": 5
        },
        {
            "ParentLinkingValue": "475750b196554658b2518fde4bfaec6e",
            "LinkFieldName": "__surrogatePrimaryKey",
            "__surrogatePrimaryKey": "556ed6b0264544bd93ebe1382578347a",
            "Name": "Griffin",
            "Age": 3
        },
        {
            "ParentLinkingValue": "475750b196554658b2518fde4bfaec6e",
            "LinkFieldName": "__surrogatePrimaryKey",
            "__surrogatePrimaryKey": "32558171e17c41f88dffc6594b4f73c3",
            "Name": "Luke",
            "Age": 1
        },
        {
            "ParentLinkingValue": "c970381d48aa4abfa92d0f46d02ead27",
            "LinkFieldName": "__surrogatePrimaryKey",
            "__surrogatePrimaryKey": "7ea305b5205844c5abde8728b68f08ae",
            "Name": "Howard",
            "Age": 15
        },
        {
            "ParentLinkingValue": "c970381d48aa4abfa92d0f46d02ead27",
            "LinkFieldName": "__surrogatePrimaryKey",
            "__surrogatePrimaryKey": "98ff8b3ccc1b4fa1a79bdee2620daee2",
            "Name": "Robert",
            "Age": 11
        }
    ]
}

%str%

Dynamic Storage Connection Strings - Storage - SQL Server Reporting Services (SSRS) - Alpha Anywhere has had the concept of dynamic connection strings for AlphaDAO connection strings for some time now. But dynamic connection strings for storage and SSRS did not exist. A dynamic connection string is particularly useful in multi-tenant SaaS applications. Now, you can define dynamic storage connection strings for both storage and SSRS.

A dynamic connection string will resolve differently based on a the value of a session variable.

To define a dynamic storage connection string, your named connection string must start with DynamicConnection_. For example: DynamicConnection_myS3Storage.

You must also have a session variable named

__protected__<name>

where <name> is the text to the right of DynamicConnection_ in the named connection string.

So for example, if your named connection string is:

DynamicConnection_myS3Storage

You would need a session variable called:

__protected__myS3Storage

When the named connection string is resolved, it will resolve to the value of the __protected__myS3Storage session variable.

Xbasic csv_to_json() Function - Escaping Doublequotes - This function now supports two different methods for escaping double quotes.

The default is use use two double quote characters. .e.g

"fred","smith","the ""computer"" store","boston"

But you can also use Javascript style escapement. e.g.

"fred","smith","the \"computer\" store","boston"

Syntax:

c json = csv_to_json(c csvtxt, c escapeMethodForQuotes)

Where:

• escapemethodforquotes - either doublequotes or backslash - manner in which the doublequote character in the data is escaped

UX Component - Frame Container - Modern Frames - If a modern frame container is configured to have a show/hide button, you can specify that if the current frame is opened and another frame is subsequently opened, the current frame will be closed.

UX Component - Mobile Applications - Panel Card - Drag Scrolling - Previously if you dragged on an input control in a Panel Card, the Panel did not scroll. Now, as long as you have not actually given focus to the input control (i.e. the keyboard has not come up) then the panel will still scroll.

UX Component - ControlBar Builder - User-Defined Templates - You can now save a ControlBar that you have designed as a template. Your user-defined templates will be listed when you click the Load Sample ControlBar hyperlink on the Home pane of the ControlBar builder.

To save the toolbar that you are currently editing in the ControlBar builder as a template, click the Save ControlBar as a Template hyperlink on Home pane of the ControlBar builder.

The dialog shown below will be displayed where you can give the template a name and a description. The description can use HTML markup.

After you have saved the template, you can save an image of how the ControlBar looks. The image filename that you must use is shown in the next dialog.

When you use the Load Sample ControlBar command the image you have saved will be shown in the list of available templates, making it easier to choose the template you wish to use.

Application Server - Publishing - The publish genie now has an option on the 'Clear Publishing History' button to clear the publish history for just the currently selected publish profile. The ability to clear all history is still available as an option.
 

UX Component - New Starter Template for Mobile App - A new starter UX template is available. The template, called MobileAppFramework_FlyInMenu_to_select_Active_Panel ) is a Panel Navigator, with multiple Panel Cards, and a Control Bar with a menu button that displays an expanding menu that flies in from the left.

Xbasic - Arrays - Change_type() Method - Changes the data type of an Xbasic array.

When you create an Xbasic array by parsing some JSON text, the array's type is set to 'A'. This is because a JSON array can contain items that are of different type.

For example, consider the following code

dim json as c

json = <<%txt%

[

    {name: "fred"},

    3

]

%txt%

dim p as p

p = json_parse(json)

If you were to check the type of p[1], (using typeof(p[1]) ), it would return 'P'.

However, if you were to check the type of p[2], it would return 'N'.

So the array elements in the array can be of any type. You can also dim an array where the items can be of any type like as follows:

dim array1[10] as A

Now consider a JSON string that defines an array in which all items are of the same type:

dim json as c

json = <<%txt%

[

    {name: "fred"},

    {name: "john}

]

%txt%

dim p as p

p = json_parse(json)

In this case all of the elements in the array are of type 'P'.

However, if you insert or append elements to the array, the new elements will be of type 'N' and not 'P' as you might have expected. This is because the internal type of the array is 'A' (as is always the case when an array is created by parsing a JSON string).

In some cases you will want to change the type of the array to a specific type so that items inserted into the array, or appended to the array are also of the same type as the other items in the array.

For example:

dim json as c

json = <<%txt%

[

    {name: "fred"},

    {name: "john}

]

%txt%

dim p as p

p = json_parse(json)

dim result as c

result = p.change_type("P")

if result <> "" then

    ui_msg_box("Error","Could not change array type: " + result)

end if

p.insert(1,1)

?typeof(p[1])

= "P"   '<<----- would have been 'N' had the .change_type() method not been called!

UX Component - ControlBar - ControlBar Builder - Pre-defined Templates - New pre-defined templates are available when you create a new ControlBar from a template and the template picker has been enhanced to show a preview of each template.

Watch Video

When you create a  new ControlBar, you can set all of the properties in the ControlBar by selecting a template (i.e. sample ControlBar). To select a template, click the Load Sample ControlBar hyperlink on the ControlBar builder Home pane.

When you click the hyperlink a window showing the templates is shown:

UX Component - ControlBar - DisclosureButtons - Disclosure Position - Three new disclosure positions are now available: flyout, flyout-element and flyout-element-cover. Using these positioning directives, it is possible to create controlbars with dropdown menus. See example below.

In the image below, the button on the toolbar opens another disclosure positioned using the flyout-element position.

NOTE Sample ControlBars that use the new flyout-element position directive can be seen by selecting the Load Sample ControlBar hyperlink on the ControlBar builder Home tab.

sql_import() function - Upsert - The SQL_Import() function is a helper function that imports new records into a SQL table. It is called a 'helper' function because it is an alternative to writing the low level Xbasic AlphaDAO commands to import data. This function now supports both 'insert' and 'upsert'. An 'upsert' performs an update on existing records and an insert if there is no existing record.

The syntax for the function is now:

p result = sql_import(connectionString as c, tableName as c , tableOwner as c, csv_or_json_data as c , replicateIdentity = .f., inputfield_to_sql_table_column_map = "", action="insert", primaryKey = "")

Where:

• connectionString - connection string to the database
• tableName - name of table you want to import or upsert into
• tableOwner - table owner
• csv_or_json_data - name/value pairs of data to import. data can either be in csv or json format. can also be the name of an Excel file.
• replicateIdentity = .f. - if the primary key is an auto-increment fields, indicates if primary key values in the input data should preserved, or if new primary key values should be assigned.
• inputfield_to_sql_table_column_map = if the field names in the input data do not match the field names in the able, a cr-lf delimited list of fieldNameInData=fieldNameInTable pairs
• action - either insert (the default) or upsert. Upsert will update existing records in the target table.
• primaryKey - primary key for the table. If the field name of the primaryKey in the input data does not match the field name of the primaryKey in the table enter the primaryKey as fieldNameInData=fieldNameInTable.

Example

p = sql_import("::name::myconnstring","table1","","c:\data\datatoimport.xlsx",.f.,"","upsert","id")

UX Component - List Control - Freeform Layout - List Item Footer - Freeform layouts now support the List-item Footer property. The state of the list item footer can be toggled on each row from open to closed, or vice versa using the <listObject>.toggleRowExpander() method.

UX Component - Multi-select Token Control - Keep List Open - A new option has been added to the Multi-select Token Control to keep the pick list of choices open after the user makes a selection.

UX and Grid Components - Arguments - Upper Case Names - When you add a new argument or rename an existing argument, the argument name is now converted to uppercase. By using the convention that argument names are always uppercase, a class of bugs that can result when the same argument name is used in multiple linked components is used and in each of these components, the argument name is defined using a different case.

UX Component - List Control - Detail View - onStateChanged Event - A new event has been added to the List control. The onStateChanged event fires when the Detail View goes from clean to dirty, or vice versa.

UX Component - Auto-Suggest and Edit-Combo Control - Multiple Selections - Keep List Open - The Auto-suggest and Edit Combo controls have always allowed you to set a mode where multiple selections can be made. However, each time you make a selection the pick list is closed and you must reopen the pick list before you can make your next selection.
 
 Now, a new property in these controls allows you to specify that the pick list should stay open after each selection, allowing you to make multiple selections more easily.

If you have turned on multiple selections, you can delete previously made selections by either backspacing to delete one character at a time, or use Shift+Cntrl+Backspace to delete complete selections.

If you have turned on multiple selections, you can prevent the user from selecting the same value more than once by setting the Allow duplicate selections property.

PhoneGap App Builder - Core Plugins And Some Key 3rd Party Plugins - Added a version specification to all core and some essential 3rd Party Plugins plugins to resolve problems with updated plugins and Android on PhoneGap Build.

Many of the core plugins were updated recently and specified a requirement for a minimum PhoneGap version of Android 6.3.0. PhoneGap Build cli-7.0.1 (the latest release supported by PhoneGap Build) includes Android PhoneGap Version 6.2.3 so the changes to the plugins configuration files causes the build to fail on the current release on PhoneGap Build. This change ensures that PhoneGap Build will work with the specified plugins.

PhoneGap App Builder - 3rd Party Plugins - Added support for the PDF417-Phonegap plugin. This plugin is a small but powerful scanner that handles bar code and PDF417 scanning.

Alpha Style Sheet - SVG Icons - Several new SVG icons have been added to the Alpha stylesheet. These are:

• anchor
• docSpreadsheet
• docSpreadsheetSolid
• logoFacebook
• logoGooglePlus
• logoInstagram
• logoLinkedIn
• logoTwitter
• logoViddler
• logoVimeo
• logoYouTube
• reorder
• reorderDown
• reorderUp

UX Component - List Control - List Virtualization - onNavigate Event - The onNavigate event's behavior is different depending on whether the list is virtualized or not. If the List is not virtualized, the onNavigate event fires when the List is scrolled. If it is, then the onNavigate event fires when the user navigates to a new page of records.

In order to allow the behavior of this event to be consistent regardless of the virtualization option, a new property has been added to the list. The onNavigate event behavior property can be set to Navigate, Scroll or Both. When set to Scroll, the behavior is the same as a non-virtualized list.

Application Server - OpenSSL - Updated to build 1.0.2m of OpenSSL.

Web Security - Utility for SQL tables in Standard Server - A revised utility has been added to the 'Utilities' option in the Web Security menu when using SQL based tables on the standard server. The new utility will still verify if the defined security tables can be found, but has additional options.

If the security system connects to the SQL tables with Active Link tables, the utility has an option to 'Validate Field Maps'. The action will verify if the field map saved in the Active Link tables map to the correct field names in the SQL table.

The option will only check a single table if one is selected. If a table is selected, the option 'Clear Selected' will remove the selection and allow checking all tables.

The option 'Show Connection String' will show the actual connection string used by a table if the table is selected. The normal configuration would have the same connection for all tables.

Errors cannot be corrected if using Active Link tables, but the utility will show a message on close if any errors were found

Changes can be made and saved if the security system is using a 'DataLink' file in place of Active Link tables. The option to 'Show Connection String' is still shown, but the option to 'Validate Field Maps' will open a genie to remap the fields if any errors were found in the existing map. The genie will only allow selecting fields that are of the correct data type and length.

A new option is shown to 'Change Connection String'. This shows a list of available connections and can change the connection for all tables. The utility will check if the current tables exist in the new connection and will run the validation option is tables with the same names are found.

Another new option is 'Select New Table'. This will show a list of tabled found in the SQL database that uses the connection. When a table is selected, the field map validation will run to allow remapping the field as needed. This option can also create a new table in the target database, but will not populate the new table with any data.

Changes can be saved by the 'Save Changes' button which is activated if any changes were made.

PhoneGap App Builder - iOS Launch Images - Added static (legacy) image generation support for iPhone X and the 10.5 inch iPad Pro launch images. If you are planning to support the new iPhone X and/or the 10.5 inch iPad Pro, you previously had to use storyboard images for your app launch image. This is no longer the case. If you choose to use static (legacy) launch images, then the appropriate size is automaticaly generated for the iPhone X and the 10.5 inch iPad Pro. Remember to center weight your image (look at Twitter's launch image) and verify that each generated image looks correct. The iOS launch images can be found in the PhoneGapProjects\ProjectName\www\res\screen\ios folder.

PhoneGap App Builder - PhoneGap Project Template The PhoneGap new project template was modified to support better code formatting for legacy (static), iOS Storyboard and Android 9-Patch launch images. These sections are dynamically replaced within the PhoneGap config.xml file when the launch and storyboard images are generated by the PhoneGap App Builder genie.

UX Component - List Control - No Records in List HTML - Specify Message Using Javascript - The List Builder allows you to specify a message to show in the List if there are no records in the List.

Previously, you could only define some static HTML to display. Now you can specify some Javascript code to return the message to be shown. To specify that the message is returned by some Javascript code, prefix the message with javascript:

For example, assume that you had defined a local function called norecordsmessage in the List Builder  (Turn on the optional Javascript tab in the List Builder and define a function at the This object level).

You would set the No Records HTML to:

javascript:this.norecordsmessage()

You can also include a5-item attributes in the message text. For example, assume you wanted to display a message if the user tapped on the no records message. Assume also that the message was to be returned by a local function called norecordsmessage(). Here is how this could be done:

First, define an item in the List Builder's Items tab (by turning on the optional Template Items tab - check the box at the bottom of the List Builder window. For example, you could define an item called 'norecords' that displayed a message when clicked.

Then define the norecordsmessage function as follows:

return '<span a5-item="norecords">List has no records</span>'

Xbasic Functions - convert_ts_to_js() - Converts TypeScript files (with .ts extension) to Javascript files (with same name, but .js extension)

Syntax

result = convert_ts_to_js(files)

Where

• result is a JSON string containing an array of errors for each input file.
• files is a cr-lf delimited list of TypeScript filenames to transpile.

UX Component - Client-side Event - OnBeforeCreate - Fires before any code to render the UX is executed. Allows you to change settings in the Alpha Anywhere Javascript library that affect how the UX is rendered. For example you could override the definition of the A5.listBox.prototype.populate() method in this code.

NOTE: The {dialog.object} object cannot be referenced in the code for this event handler as it has not yet been instantiated.

Xbasic - a5_XbasicTreeToJSONTree() Function - This function, which takes a CRLF delimited string, and converts it into a complex JSON structure that can be used to populate a Tree or Menu control, has been enhanced and now allows you to define the Javascript code to execute when the user clicks on a tree leaf.

Consider the following example, which produces a tree showing Countries, Cities, then ContactName. ContactName is the tree leaf. When the user clicks on a leaf, you want to call a Javascript function. The data for the tree should come from a SQL query.

Here is how this is achieved:

dim cn as sql::Connection
cn.open("::Name::northwind")
cn.PortableSQLEnabled = .t.
dim sql as c
dim flag as l

'define the sql query that will return the data in the correct format
sql = <<%str%
select country, city, concatenate(contactname,'```onclick:findCustomer(','''',customerId,''')') from customers where not (country = '') order by country, city, contactname
%str%

flag = cn.Execute(sql)
dim txt as c
txt = cn.ResultSet.tostring(-1,-1,.t.,"|")
'this will generate a crlf delimited string like this
'France|Nantes|Carine Schmitt```onclick:findCustomer('FRANR')
'France|Nantes|Janine Labrune```onclick:findCustomer('DUMON')
'France|Paris|Dominique Perrier```onclick:findCustomer('SPECD')
'France|Paris|Marie Bertrand```onclick:findCustomer('PARIS')
'France|Reims|Paul Henriot```onclick:findCustomer('VINET')'

'notice that the tree branches are separated by a | character.
'the leaf nodes specify an onclick event.
'the syntax for the onclick event is ```onclick:javascript to execute

'notice that we pass the primary key to the leaf as the argument to the function

txt = a5_XbasicTreeToJSONTree(txt,"|","html")

The resulting JSON string is:

[
  {
    "html": "Argentina",
    "children": [
	          {
		    "html": "Buenos Aires",
		    "children": [
			          {
				    "html": "Patricio Simpson",
				    "onClick": function() { findCustomer('CACTU')}
				   },
				   {
				     "html": "Sergio Gutiérrez",
				     "onClick": function() { findCustomer('RANCH')}
				   },
				   {
				     "html": "Yvonne Moncada",
				     "onClick": function() { findCustomer('OCEAN')}
				   }				
		]
           }

   }......
]
			

UX Component - Spreadsheet Input Control - Get and Set Column State - Two new methods have been added to the control

• .getColumnState() - returns a JSON object with the definition of all of the columns in the controls. The definition includes the width of each column. You can get the definition and store it in local storage. Then, the next time the UX is run, you can use the .setColumnState() method to restore the Spreadsheet input control to its previous state.
• .setColumnState(jsonDefinition) - takes a JSON object (typically created using the .getColumnState() method) and sets the columns in the Spreadsheet input control.

Example

var obj = {dialog.object}.getControl('myspreadsheetcontrol_1');

var json = obj.getColumnState()

//store the column state in local storage

localStorage.setItem('columnstate',json);

//restore the column state

var obj = {dialog.object}.getControl('myspreadsheetcontrol_1');

var json = localStorage.getItem('columnstate');

obj.setColumnState(json);

UX Component - List Control - Media Files - Events - In a disconnected application you can configure the media files in the List to download to the mobile device and be stored in the filesystem on the device. The UX component will fire the beforeMediaFiles download and afterMediaFilesDownload events. Previously, even if there were no media files to download, these events would fire. Now, if there are no media files to download a new event, onNoMediaFilestoFetch will be fired.

UX and Grid Components - Reports - Send via Email - A new option in the Action Javascript command to display a report, now allows you to email the report rather than displaying it.

When you check the Email report property the Email settings property is shown when you can configure the email that will be sent with the report as an attachment.

The Email Settings dialog is shown below.

UX Component - Frame Control - Modern Frame - Set Open/Close State Programmatically - A new method allows you to set a modern frame to be open. closed, or to toggle its state.

The method, {dialog.object}.frameOpenStateChange(frameId, state) takes two arguments:

• frameId - the Id of the frame control
• state - can be open, closed or toggle

Bugs

Alpha Style - IE 11 - Browser Hang - Under some circumstances it was possible to hang IE 11 when using a Grid or UX component that used the Alpha style. The Alpha style uses SVG icons for all icons shown in the components. If a button had an SVG icon and you clicked directly on the icon, and as a result of the click, the icon was replaced (perhaps with a disabled version of the icon), IE11 would occasionally hang.

UX Component - SpreadsheetInput Control - Column Width - The column width property was not being honored when the control was rendered.

Alpha Anywhere Server for IIS - Install Error - An install error introduced in approximately build 4710 has been corrected.

bus_days_between() Function - Fixed a bug in this function when using a .dbf table for the list of holidays. The bug did not exist when using a SQL table for the holiday list.

AlphaCloud - All Components - Local CSS - SASS - If any local CSS defined in a component used SASS syntax, the definition was not properly converted to CSS. This bug was a recent regression.

SASS Processing - This build now includes a new version of the SASS processor that converts SASS to CSS. This new SASS processor can report errors in the input SASS file.

UX and Grid Components - Client-side Watch Expressions - Stack depth exceeded Error - Certain types of client-side watch expression (for example myFunction('{grid.componentName}'), would cause a 'stack depth exceeded' error message when the component was saved.

Page Layout Component - Fixed an issue when a Page Layout component contained a Grid component.

Tips

UX Component - Edit-Combo Control - Automatically Displaying the List of Choices - In some situations you might want the pick list for an edit-combo box to be displayed automatically as soon as the user gives focus to the control.

This is easily done by getting a pointer to the button that opens the pick list and then calling the object's .click() method.

For example, assume that the variable name for your edit-combo control was MYEDITCOMBO. You could add this code to the control's onFocus event:

ele = $('DLG1.V.R1.MYEDITCOMBO.BUTTON');
ele.click()

However, on a mobile device this will not work because the events are all abstracted on a mobile device. To get the above code to work on a both a standard desktop browser and a mobile device change the code to use the $e.execute() method, which allows you to execute abstract events.

ele = $('DLG1.V.R1.MYEDITCOMBO.BUTTON');
$e.execute(ele,A5.d.evnts.click);

Videos

Features

{dialog.Object}.frameOpenStateChange(frameId,state)"
a2[..].description = <<%html%
Sets the open/closed state of a Frame control. Frame control must be configured as a 'Modern' frame and must have
the 'Has show/hide buttons' property checked. Where: <br>
 

PhoneGap App Builder - Added PhoneGap CLI Support for Cordova Version 7.0.1  - Added support within the PhoneGap CLI builder for Cordova Version 7.0.1, Android Studio 2.3.3 and XCode Version 9.0.

Handling of Launch Images, Splashscreens and Icons was modified and tested with the latest releases of PhoneGap, Android Studio and Xcode.

Note: The script for Android Studio 2.3.3 was modified to kill all aapt.exe (Android Asset Packaging Tool) instances that remain open after a successful Android Cordova Build. This appears to be a bug in the Windows Android SDK or Cordova 7.0.1.

Xbasic - JSON - extension::json::ForEachString() Method - This method is similar to the Xbasic *for_each() function, except that it is designed to operate on property values in a JSON string.

For example:

dim json as c = <<%str%
{
    "name" : "name Smith " ,
    "alias" : [ "jj " , "name " ] ,
    "id"     : {
        "name" : "name_01 "
    }
}
%str%
 

Notice that the string 'name' appears in the above JSON as both a property name and also in a property value.

We want to change 'name' to 'John', without changing the names of any of the property values. Also, note that each property value has trailing spaces.
 

'change 'name' to 'John'

json = extension::json::ForEachString(json,"strtran(value,'name','John')")
 

'trim trailing spaces from each property value
json = extension::json::ForEachString(json,"trim(value)")
 

Result:

{
    "name" : "John Smith" ,
    "alias" : [ "jj" , "John" ] ,
    "id" : {
        "name" : "John_01"
    }
}
 

Notice that none of the property names were changed.

UX Component - SpreadsheetInput Control - A new control type is now available in the UX component. The SpreadsheetInput Control allows you to display a spreadsheet style grid of cells in which the user can enter/edit data. The spreadsheet columns can be resized and also reordered.

For example, in the image below, a SpreadsheetInput Control has been defined with 3 columns and 5 rows. The user can use keyboard navigation (tab, shift-tab, up and down ) to move between the cells in the control.

Watch Video - Part 1
Watch Video - Part 2
Watch Video - Part 3

Download component

When the UX is submitted, the data in the control is submitted as a JSON string.

For example, if the control had been filled in as shown below:

then, when the UX was submitted, the data submitted for the SpreadsheetInput control would be as string with this value:

"[{"field1":"alpha","field2":"beta","field3":""},{"field1":"","field2":"","field3":"gamma"}]"

To, add a SpreadsheetInput control to a UX, select the [More..] control from the Data Controls section of the UX toolbox.

Then select the SpreadsheetInput control from the list.

To configure the control, click the smart field for the Control properties.

This will open the genie where you can configure the control.

The most important property to configure is the Column definitions property. This property allows you to define the columns shown in the SpreadsheetInput control.

Click the smart field to open the editor, as shown in the image below.

You can add columns one at a time by clicking the Add Column button. You can click the Quick Select using Genie hyperlink to add columns to match the fields in a SQL table.

The onNavigate property allows you to specify Javascript code to execute when a cell in the control gets focus.

Defining Row Prefixes and Suffixes

You can define row prefixes (i.e. row labels) and row suffixes so that the control looks even more like a spreadsheet. The prefix displays at the left side of each row and the suffix displays at the right edge of each row. For example, in the image below a prefix has been defined to show the row number.

Here is how the control is configured to show the prefix:

The Has row prefix (label) property is checked.

The Row prefix HTML is a defined using Javascript code that can reference row - the zero based row number and data - the array of data with which the control is populated. To show the row number as the row prefix, the Javascript for the Row prefix HTML is set to:

return (row + 1);

The Width property is set to 50px to set the width of the prefix column.

The Style property is set to font-size: 75%; text-align: right; to make the font slightly smaller than the text in the input control and also to right align the text in the row labels.

Methods

Since the SpreadsheetInput control is a standard UX Data Control, you can use the {dialog.object}.setValue() method to populate the cells in the control with data and the {dialog.object}.getValue() method to get the data in the control. When you use these methods, the value is a JSON string.

For example, if the SpreadsheetInput  control has 3 columns (field1, field2 and field3), you could use the following Javascript to populate the control:

var _data = [

    {field1: 'alpha', field2: 'beta'},

    {field2: 'gamma', field3: 'delta'},

    {field3: 'epsilon'}

];

var _string = JSON.stringify(_data);

{dialog.object}.setValue('mySpreadsheetControl',_string);

.setColumnAndPopulate() Method

You can also dynamically change the columns shown in the control to match the columns in some data with which you want to populate the control. For example, say that the SpreadsheetInput control was initially configured to show a single column (say 'Field1') and you wanted to populate it with the the following data:

[

    {firstname: 'John', lastname: 'Smith', city: 'London'},

    {firstname: 'Harry', lastname: 'Jones', city: 'Boston'},

    {firstname: 'Winston', lastname: 'Flowers', city: 'Harare'}

]

You can call the control's .setColumnsAndPopulate() method.

For example:

var obj = {dialog.object}.getControl('mySpreadsheetControl');

var _data = [

    {firstname: 'John', lastname: 'Smith', city: 'London'},

    {firstname: 'Harry', lastname: 'Jones', city: 'Boston'},

    {firstname: 'Winston', lastname: 'Flowers', city: 'Harare'}

]

obj.setColumnsAndPopulate(_data);

The columns shown in the control will now be 'firstname', 'lastname' and 'city'.

.getColumnState() and .setColumnState() Methods

Since the columns in the Spreadsheet input control are resizeable and reorderable, you might want to capture the state of the Spreadsheet input control's column layout so that you can restore it the next time the user runs the component.

For example

var obj = {dialog.object}.getControl('myspreadsheetcontrol_1');

'get the spreadhseet control state as a JSON string

var json = obj.getColumnState();

'store in local storage

localStorage.setItem('spreasheet_01_State',json);

Then, to restore the state

var json = localStorage.getItem('spreasheet_01_State');

var obj = {dialog.object}.getControl('myspreadsheetcontrol_1');

obj.setColumnState(json)

UX Component - Client-side Events - onWatchEvent - A new client-side event has been added. The onWatchEvent fires when any of the client-side watch events (show/hide, enable, readOnly) fires. For example, when a client-side show/hide expression on a control is executed the event is fired. The type of event, the name of the control on which the expression is being evaluated and the result of the expression are passed into the event handler.

Possible values for the type parameter passed to the event handler are

• show/hide
• show/hideTabPane
• enable
• enableTabPane
• readonly

UX Component - Set Tab Order - By default, the tab order in a UX component is the same as the order in which the controls were defined. However, you can now define a custom tab order without having to reorder the controls in the builder.

To open Tab Order dialog, select the Set tab order... menu item in the dropdown Menu

In the dialog, select the tab order that you want.

UX Component - List Control - Event - onBeforeListClear - Fires before the list data is cleared.

UX Component - Client-side Events - canAjaxCallback and onAjaxCallbackComplete - callbackId Parameter - A new parameter is available in the e object passed to these events. The e.callbackId property is a GUID that identifies the callback and allows you to match the onAjaxCallbackComplete event with a particular AjaxCallback.

UX Component - List Control - .setDisplay() Method - This method has been enhanced and can now be used to operate on List columns.

For example, the following method will hide columns 0, 1 and 2 in a columnar List layout:

var lObj = {dialog.object}.getControl('list1');

lObj.setDisplay('column',{column: [0,1,2], display: [false,false,false]})

Documentation - List Control - The documentation system now contains in-depth description of the List object. Note that in the documentation the List is referenced as ListBox, its official internal name.

NOTE: The documentation referenced here does not include the List control methods that are only available when the List has a Detail View. These methods are currently documented here.

PhoneGap Builder : Added support for PhoneGap Build Version cli-7.0.1

PhoneGap Build recently added support for PhoneGap 7.0.1 which aside from security and performance enhancements includes some important changes behind the scenes in the build infrastructure. There are now two distinct builders that can be used by PhoneGap Build, the original and the new and this option is exposed in the Alpha PhoneGap App Builder as the PhoneGap Builder Version property, values 1 and 2. By default this value is set to 1 which will use the original builder which will most likely be deprecated at some point in the future. If you set this option to 2, then the new builder will be used by the PhoneGap Build Service.




If you plan to support the new iPhone X, you will need to use storyboard launch images (now supported, see below) and you must use cli-7.0.1 and PhoneGap Builder Version 2.

Please see the PhoneGap Build Blog PhoneGap 7.0.1 Release Notes for all of the details on the cli-7.0.1 release.

PhoneGap Builder: Added support for iOS Storyboards and Android 9 Patch images

With the release of PhoneGap Build cli-7.0.1, support for iOS Launch Storyboards is now inherently supported within the new builder. If you plan to support the new iPhone X or the iPad Pro 12.9’s native resolution or split screen/slide-over multitasking, you’ll need to use iOS storyboard launch images.

Launch storyboard images are sized based on scale, idiom, and size classes. They supports all devices, and can be used with split-screen/slide-over multitasking.




Apple is moving away from legacy launch images. There is no official support for providing a native-resolution launch image for the iPad Pro 12.9 or for providing launch images that work with split-screen multitasking or slide-over. If your app doesn't need to support these contexts, then you can continue to use legacy launch images for as long as you like.

The preferred method of providing launch images is to use a launch storyboard.

These are similar to the legacy launch images, but there are crucial differences:

• images are not specific to a given device.
• images are scaled to fill the available viewport (while maintaining the aspect ratio).
• the outer edges of the images will be cropped, and the amount will vary based on device an viewport.
• there is no need to provide an image for each possible device, viewport, and orientation; iOS will choose the best image for the situation automatically.

Designing launch storyboard images (Applies to Android 9-patch images as well)

The key to designing a launch storyboard image is understanding that the edges of the image will almost certainly be cropped. Therefore, one should not place any important information near the edges of any images provided to the launch storyboard. Only the center is a safe area, and this all but guarantees that following Apple's advice of presenting an unpopulated user interface will not work well.

Instead, the following tips should enable you to create a launch image that works across a multitude of form factors, viewports, and orientations:

• Important graphics (logos, icons, titles) should be centered. The safe bounding region will vary, so you will need to test to ensure that the important graphics are never cropped. Better yet, don't supply any important graphics in the first place.
• You can fine-tune the placement and size of these graphics, but you don't have the same fine-grained control as you did with legacy launch images.
• Use a simple color wash. If you use two colors, you'll want one color to fill the top half of the image, and the second to fill the bottom half. If you use a gradient, you'll probably want to ensure that the middle of the gradient lines up with the center of the image.
• Don't worry about pixel perfection -- because the images are scaled, there's almost no chance the images will be perfectly fit to the pixel grid. Since all supported iOS devices use retina screens, users will be hard pressed to notice it anyway.

Of the images supplied to the launch storyboard, iOS will choose the image that best matches the device and viewport and render that image.

The Alpha PhoneGap Builder will generate all of the rerquired storyboard images from a single user supplied square 2732px x 2732px (min) png file. The iOS storyboard file is generated from the image specified for the Portrait splash screen.

Changes to the PhoneGap Build config.xml file

The Alpha Anywhere PhoneGap App Builder will automatically remove and replace certain sections of the config xml file that reference legacy splashscreens, storyboards or Android 9-patch images, based on the properties set within the builder. All of the sections are marked with XML comments and those comments need to remain in place. If legacy splashscreens are specified then the sections for the storyboard and Android 9-patch images are removed, but the comment tags are left intact. If storyboards and Android 9-patch images are specified, then the legacy sections are removed.

If you are modifying an older PhoneGap project with a legacy config.xml file (the comment tags we added around April of 2017), these sections will be added to the older config.xml file and a message will be displayed, indicating that an older config.xml file was modified. In this case, you should edit the config.xml file to remove the older legacy splashscreen section, prior to submission to PhoneGap Build.

Grid Component - Arguments - Session Variables - Arguments that are bound to session variables are now updated on every Ajax callback. Previously, the argument values were only set when the Grid was initially run.

Xbasic - email_send_sparkpost() Function - SparkPost Options - SparkPost allows you to specify options, such as open_tracking and click_tracking (see SparkPost API documentation).

You can now pass in these options to the email_send_sparkpost() function as shown below:

dim ms as p

'xbasic commands to set required properties of mp not shown

ms.options.open_tracking = .f.
ms.options.click_tracking = .f.
dim key as c = "your sparkpostkey"

dim pp as p
pp = email_send_sparkpost(key,ms)

UX Component - DropdownBox Controls - Client-side Data Cache - DropdownBox Box controls can now be populated with data that is stored in the Client-side Data Cache.

This is particularly useful in the case of mobile applications that are deployed as PhoneGap applications, or in static HTML applications that use the Application Cache, because in these applications the DropdownBox controls are populated with data at the time the application in built. When the applications are run, the DropdownBox controls will still continue to show the data that they were populated with at build-time.

In many cases it will be desirable to update the choices shown in a DropdownBox with up-to-date data and to continue to use the most up-to-date data available when the App is launched, even if there is no connection available at that time.
To solve this problem, you can populate DropdownBox controls with data from the Client-side Data Cache.

In order to indicate that data from the Client-side Data Cache should be used, set the first line of the static choices to this:

client-side-data-cache:cacheItemName(displayDataColumn,storedValueColumn)

When the App is launched, if a connection is available, the Client-side Data Cache will be refreshed and the DropdownBox will be populated with fresh data. If no connection is available the first time the App is launched the choices you specify in the second and subsequent lines of the defined Static choices will be used.

For example, assume you had a Client-side Data Cache item called Products and that this item had two columns, Description and Code. In order to populate the DropdownBox to use the Description field as the display value and the Code field as the stored value, you would use this directive in the first line of the Static Choices:

client-side-data-cache:Products(Description,Code)

If you want the display value and stored value to be the same, then just specify the name of the display value column for the stored value.

client-side-data-cache:itemName(displayColumn,storedValueColumn)

The image below shows how the choices in a DropdownBox control would be defined to read the data from a Client-side Data Cache item called weekdays.

The choices shown starting on line two are the fallback choices that will be used if there is no connection available the first time the App is launched (which means that the Client-side Data cache cannot be populated).

Xdialog - Dynamic Titles - It is now easier to dynamically change the title on an Xdialog. The {title} directive can now display the value of a variable. When the value in the variable changes, the Xdialog title is also changed.

To specify that the {title} directive should use a variable, use this syntax:

{title=@variable_name}

Example:

dim dyn_title as c = "The Title"
ui_dlg_box("dynamicTitleExample",<<%dlg%
{title=@dyn_title};
Title [.80dyn_title!change];
{line=1};
{justify=right}<&Ok>
%dlg%,<<%code%
if a_dlg_button = "change" then
    a_dlg_button = ""
end if
%code%)

 

Clone Workspace - You can now clone a Workspace. The Clone Workspace command is on the File menu when the Web Control Panel or the standard Control Panel have focus.

UX Component - Slider Controls - Client-side Data Cache - You can now set the data in a slider control based on data in a Client-side Data Cache item.

UX Component - Client-side Events - afterControlBasedOnClientSideDataCacheRefreshed Event - Several control types (e.g. SpinList, ButtonList, Slider) can be populated from data in a Client-side Data cache. This event fires after a control that is populated from a client-side data cache item has been populated.

UX Component - Expanding Menu Control - Define Menu Choices Using JSON - You can now define the menu choices in an expanding menu control by defining a JSON object.

Xbasic - Handlebars.js Templating Library - You can now use the popular Handlebars.JS templating library in Xbasic code.

NOTE: The Alpha Anywhere templating library is also available to Xbasic code through the a5_merge_JSON_into_template() Function.

Example:

dim hb as nodeservices::handlebars

dim source as c = <<%str%
<p>Hello, my name is {{name}}. I am from {{hometown}}. I have
{{kids.length}} kids:</p>
<ul>

{{#kids}}

    <li>{{name}} is {{age}}</li>

{{/kids}}

</ul>
%str%
 

dim json as c = <<%str%
{
    "name": "Alan",
    "hometown": "Somewhere, TX",
    "kids": [

        { "name": "Jimmy", "age": "12" },

        { "name": "Sally", "age": "4" }

    ]   
}
%str%

html = hb.RunTemplate(source,json)

 

Resulting text:

<p>Hello, my name is Alan. I am from Somewhere, TX. I have
2 kids:</p>
<ul>

    <li>Jimmy is 12</li>

    <li>Sally is 4</li>

</ul>
 

UX Component - SpinList and ButtonList Controls - Client-side Data Cache - You can now specify that the data source for a SpinList or ButtonList control is a Client-side Data Cache item. This is particularly useful in PhoneGap applications that are designed to work offline. Here is why:

Say you build a UX component that has a SpinList control and you specify that the control should be populated with data from a Data Series. At the time your PhoneGap application is built, the SpinList with be populated with the data in the Data Series.

Once the PhoneGap app is installed on a device, the SpinList will continue to have the data that was in the Data Series at the time the PhoneGap app was built. If you refresh the Data Series the SpinList will now have up to date data, but this data has not been persisted on the device. So, this means that if you exit the App and re-launch it you are back to having stale data in the SpinList. If you do not have a connection you would not be able to make a callback to the server to refresh the data in the SpinList.

However, if you specify that the SpinList is populated from data in a Client-side Data Cache, the Client-side Data cache will be refreshed automatically when the App is launched and then the SpinList will be populated with the up-to-date data. The data that was retrieved from the server will be persisted on the device (assuming the Client-side Data Cache item was configured to persist data on the device). This means that if you exit the App and then re-launch it (while no connection is available), the SpinList will be populated with the data that was fetched from the server the previous time the App was launched (presuming that at that time a connection to the server was available).

UX Component - List Control - Search Part - Server-side After Search Expression Computed Event - New server-side event when performing a search on a List using the List's Search Part.

The Grid component exposes a server side event, onSearchPartFilterCompute, that allows developers to override the filter that was computed from the submitted search data. This event fires before the actual search query is executed.

Analogous behavior can now be added to searches performed from the Search Part of a List control.

The Javascript method to invoke a search is as follows:

{dialog.object}.getControl('name_of_your_list').searchList( searchOptions)

where searchOptions is a JSON object with these properties:

• searchMode - auto, clientSide, serverSide   (auto will execute a serverSide search if the List does not have any unsynced edits)
• xbasicAfterFilterCompute - this is a new property. It is optional. It defines the name of an Xbasic function that will be called after the filter has been computed, but before the SQL has been executed.

For example:

{dialog.object}.getControl('LIST1').searchList({searchMode : 'auto', xbasicAfterFilterCompute : 'xbmodifysearch'});

The Xbasic function takes e as an input parameter.

The e object contains:

• e.tmpl - pointer to the UX component definition
• e.searchDefnition - an object with various properties defining the filter expression computed by Alpha Anywhere from the submitted data.
  
   

e.searchDefinition contains these properties

• parameters -- values for the arguments used in the filter expression. Syntax is a CR-LF delimited string with syntax for each line as:

 searchValue|||field type|argument name

For example:

%UK%|||C|search_country_country1

• filter - the SQL Where clause to be added to the base SQL query for the List.

For example:

(Country LIKE :SEARCH_Country_Country1)
 

• order - the SQL order clause
• having - the SQL having clause
• distanceFromLocation - used in geography searches

Your Xbasic function can modify any of the properties in the e.searchDefinition object.

Videos

Features

UX Component - Client-side Data Cache - A new option to automatically refresh the Client-side Data Cache before reading it has been added to the following actions in the Client-side Data Cache action in Action Javascript:

• Read Data
• Read Multiple Data Items

When you read the value in a client-side data cache item that has been persisted to storage on a device (either local storage or the file system if in a PhoneGap application), the existing value in the cache will be returned. If you wanted to ensure that you were getting 'fresh' data you would need to first execute an action to refresh the Data Cache. Now you can combine the refresh and read actions into a single step. Both the 'Read Data' and 'Read Multiple Data Items' actions now have a new property - Refresh cache items (if on-line) before read.  When you read an item, the cache will first be updated (if the device is on-line and the Alpha Anywhere server is available) and then the refreshed cache will be read. If the device is not on-line, or the Alpha Anywhere server is not available), then the existing data in the cache is read and returned.

UX Component - Client-side Data Cache - Client-Side Data Cache Action in Action Javascript - The Refresh Data Item(s) action now allows you to specify Javascript to handle these situations:

• onFail - The Ajax callback failed to return a response
• onDeviceOffline - the device is off-line
• onServerNotAvailable - the device is on-line, but the Alpha Anywhere server is not on-line.

Web Control Panel - Bulk Operations UX Components - The bulk operations 'Recalculate UX components' and 'Turn Pre-render option on for UX Components' have been replaced with a new single genie for updating UX components. It is listed in the Web Control Panel menu option Edit -> Bulk Operation as 'Update UX components'

This new genie has options to filter the list of components by filtering by the 'pre-render' property, the file save type (binary or JSON), and if the component was last saved in an older build. This can make selecting the components to update easier. The update options include the original recalculate option and a new option to recalculate all controls as part of the update. Selected components can be changed to pre-render or have the pre-render option removed. The component save format (binary or JSON) can be changed at the same time. The genie includes help to explain the various options.

Some update options will automatically change the filters to show appropriate components. For example, if you select to change components to 'pre-render', only components that are not already pre-rendered will be shown.

Web Security - Using SQL Data - Use DataLink File - A new option has been added to the web security settings when using SQL based tables. A special encrypted single DataLink file is used to store all of the connection data needed to connect to the defined back-end SQL security tables. This file is named 'DataLink.SecuritySettings' and will always be included in every publish with other security settings files. Active Link tables for security are not used with this option and will be removed from the web project when the 'Use DataLink File' option is selected. If the DataLink option is not selected or removed, the original Active Link tables will be recreated as required.

When a DataLink file has been published, the original security Active Link files named 'websecurity_*.*' will not be used and can can be deleted from the published web project. A published application will always use the DataLink.SecuritySettings file if it exists.

UX Component - List Control - New Control Types - Several new control types are now available for displaying data in a List. These are:

• Switch - displays a value using a two state switch control
• Integer - displays an integer value with buttons to the left and right of the value to increment/decrement the value. You can display buttons that change the value by 1, 10, or 100.
• Radiobuttons - displays a value using a button list. The control behaves like a radio button because only one value in the button list can be selected.
• Checkbox - displays a value using a button list. The control behaves like a checkbox control because multiple values in the button list can be selected. The selected values are stored as a comma delimited list. For example, if the user selects the Red and Green buttons, the value stored in the List is Red,Green
• Map - display a value using a Map. The value (which must be a comma delimited string with a latitude and longitude value) is shown as a marker on the map.
• Javascript - allows you to define a Javascript function that returns HTML that is displayed in the List. The Javascript must be defined as a List method (i.e. it must be defined in the List builder on the Javascript pane). The method must take these input parameters: value - the value of the field, data - the array of data for all rows in the List, rowNumber - row number of the row being rendered (zero based), fieldName - the field name of the field being rendered.

The images below show the various control types.

Watch Video

Download component

To select any of the above List Column control types, go to the Fields tab in the List builder and click the smart field for the Control type property.

UX Component - Keyboard Shortcuts - You can now define keyboard shortcuts for a UX component.  The shortcuts can run Javascript Actions, click a button, or execute arbitrary Javascript code.

Watch Video
Download component
 

To define Keyboard shortcuts, click the smart field for the Keyboard shortcuts property in the UX builder.

This will open up the genie where you can define key combinations and the corresponding action for the key combination.

UX Component List Control - Columnar Layouts - Column Footer - You can now define footers for columns in a List control.

The ability to define column footers is particularly useful when you want to display summary data (such as totals, averages, etc.) at the bottom of a column of data.

For example, in the image below the total for the Quantity column is shown in column footer for the Quantity column.

Watch Video

Download component
 

In the above example, the total was added to the column footer for the Quantity column as follows:

1. On the Fields tab of the List builder, the Compute summary values option for the Quantity field was checked. This option computes the summary values on the client-side (after the List has been rendered)

2. The following HTML markup was added to the Column Footer Template for the Quantity column:

<div>
Total: <span id="{dialog.componentName}.{dialog.listid}.QTY.TOTAL"></span>
</div>

3. The following code was added to the afterClientSideSummaryCompute event. The code writes the value for the Quantity total to the element with the id of {dialog.componentName}.{dialog.listid}.QTY.TOTAL. This element was placed in the footer template for the Quantity column. By using the placeholders, {dialog.componentName} and {dialog.listid} in the id, we ensure that the Id is unique.

UX Component - List Control - Template Commands - New directives are available for use in the List template. These are:

• {*if [temp].info.isFirst} - true when rendering first row in List
• {*if [temp].info.isLast} - true when rendering last row in List
• {[temp].index} - row number in the List's _data array
• {[temp].renderIndex} - row number in the List's _rData array. (This is the filtered/sorted array of data shown in the List)

Request Enhancements - A new option on the Help menu allows you send enhancement requests to the Alpha Anywhere development team.

UX Component - List Control - Reorder Rows by Dragging on Row - You can now easily implement a pattern where the user drags a row in a List to a new position.

Watch Video - Part 1
Watch Video - Part 2

Download component

To turn on drag-reorder behavior, open the list builder and check the Has row drag reorder behavior property in the List builder on the List Properties pane.

Then open the settings builder.

The builder allows you to specify two different modes of operation, DownHold and Handle.

In the DownHold mode, the user presses and holds on the row to be moved. The List then switches to reorder mode and the user can drag the row to its new location.

In Handle mode, the user simply drags on a portion of the row that has been designated as the drag handle to drag a row to its new location. Dragging on any other portion of the row simply scrolls the List. Typically a icon is used to designate the drag handle, and the icon is hidden until the user puts the List in reorder mode (using some Javascript).

When you click the smart field for the Mode option, a dialog is displayed explaining the modes.

Notice when you select the Handle option, a hyperlink is displayed that will show sample HTML, CSS and Javascript to hide the drag handle until the user explicitly puts the List into reorder mode.

UX Component - List Template Items - You can now display a tab in the List Builder for List template items. Previously you had to open a modal dialog window when you wanted to define or edit List template items.

NOTE: List template items are inserted into a List template using the a5-item attribute in the HTML markup for the List.

You can control the visibility of the Template Items, CSS and Javascript tabs by checking the appropriate checkboxes at the bottom of the List builder screen. If your List definition contains control CSS , items, or user-defined List methods (Javascript), the appropriate tabs are automatically displayed when the List builder is first opened.

UX Component - List Control - CSS - Control Level CSS - You can now define CSS for a List control. This CSS is scoped to the List.

This means that if you have two List controls on a UX and in the first List control you define a CSS selector called .myclass1 as color:red; and in the second List control you define a CSS selector also called .myclass1 as color:blue; the CSS selector defined in the second List will not override the selector defined in the first List.

The List builder now has a new pane where you can define this control level CSS.

NOTE:  The advantage of CSS defined at the Control level (besides the fact that it is in its own namespace) is that the List is fully defined in the List definition. It does not rely on any CSS classes that are in linked CSS stylesheets or in local (to the UX component) CSS definitions. If you copy the List from one component to another, it will still render correctly.

You can use SASS syntax when defining the control CSS.

UX Component - List Control - Drag on Row - You can now add support for drag actions on a row in a List. You can define actions for both left-to-right and right-to-left drag actions. For each drag action you can define one or more buttons that are revealed as the user begins dragging on a row.

Watch Video - Part 1
Watch Video - Part 2

Download component

The sequence of images shown below shows a List with both left-to-right and right-to-left drag actions defined in its different states.

This image shows the list with the first row selected and before user has dragged in either direction on the row.

This image shows the List after user begins dragging from left-to-right. Notice that the action button is partially revealed because the user has not dragged sufficiently far to the right.

The user has now dragged sufficiently far to the right and has released her finger from the screen. The action button is now locked in place. User can invoke the action by tapping on the button.

The user can continue dragging to the right past the specified threshold distance. The action button keeps on expanding in size. If the user removes her finger from the row the action will automatically be selected. User does not have to tap on the button to select the action.

In this image the user has previously selected the Unread action to mark the status on the row to read. Now the user has dragged again all the way to the right and the label on the action button has changed from Unread to Read. Releasing on the row will invoke the action and mark the row as read. If, instead of releasing, the user drags back in the opposite direction (toward the left), the action button will gradually be hidden and the action will not be invoked

This List is shown in its normal state after the user has selected the Unread action. Notice that the icon on the row has changed to indicate that the row has been read.

The user now starts dragging from right-to-left. Three action buttons have been defined for this action. The action buttons are only partially shown because the user has not dragged sufficiently far. If the user were to release now, the action buttons would be hidden and no action would be invoked.

The user has now dragged sufficiently far to the right to fully reveal the three action buttons. If the user releases now the action buttons remain visible in the row. Tapping on one of the buttons will invoke the action. Tapping in the area to the right of the buttons will not invoke any action and the List row will be returned to is normal state.

If the user continues dragging on the row (past the threshold distance) after all of the action buttons are fully revealed, the outermost action button (Archive) is auto selected and it begins to fill the row. If the user releases now the Archive action will automatically be invoked.

To define row drag settings open the List builder and check the Has custom row drag behavior property on the List Properties pane.

Then open the genie by clicking on the smart field for the Row drag settings property.

TiP: You can get to the Row drag settings genie more quickly by clicking the Quick Access... button at the bottom of the List builder and then selecting Row drag settings from the menu.

The List Row Action Builder genie is shown below. The builder has two panes. The Action Buttons pane is where you define the action buttons for the drag actions. The Actions pane is where you define the Javascript code to execute when each action button is selected.

NOTE: When you drag on a row and select an action, the row you dragged on does not automatically become the selected row in the List. If a previous row was selected, this row remains selected. If you want the row you drag on to automatically be selected, add this code to the Javascript for the Action:

this.setValue(index);

UX Component - List Control - Lazy Image Loading - Virtualized List - The code that the genie generates has been changed so that if your list is virtualized and you scroll back to a page of List records that have previously loaded images, the spinner will not be shown for the previously fetched images.

UX Component - List Control - Star Rating - You can now display data in a List column using a StarRating control. Tapping on one of the stars in the control will update the value in the List.

Watch Video
Download component

For example, in the image below, the selected row in the List (which has an associated Detail View) was edited by tapping on a star and the List row is shown as dirty.

To display data in a List column using a Star control, set the Control type for that field to StarRating in the List builder Fields tab (as shown below).

UX Component - Color Picker - A new color picker is now being used in selected parts of the UX builder.

The color picker has several modes that make selecting colors easier and faster.

The color picker also has support for semi transparent colors (when set into either 'rgba', 'hsla' mode).

In the image below, the 'Fan Decks' (like paint swatch sheets that you get from a paint store) allows you to select from a series of predefined colors.

On the left you can select any color and transparency that you want by dragging the sliders.

The selected color is shown in the rectangle at the top left.

In the top right corner of this rectangle a much smaller square is shown. This is the color that was originally selected when the color picker was first opened. It allows you to quickly switch back to the initial color by clicking on the color square.

In the Palettes mode (shown below) you can select from a palette of pre-defined colors that you define.

You can easily add a new color to the palette by selecting a color in the left hand pane and then clicking the + icon in the Palettes pane.

Another way to add a color to the palette (when the Palettes mode is not selected) is by clicking on the

button in the left hand pane.

You can manage your palettes by clicking the down arrow icon in the Palettes mode

In the Image mode (shown below) you can load an image into the image picker and then select colors by pointing to different parts of the image.

You can set the mode in which the color picker works by clicking on the button (shown as HEX in the above image)

This brings up a menu showing the mode.

UX Component - Star Rating Control - Color of Un-selected Stars - You can now set the color of un-selected stars as show in the images below. The top image shows the current default color and in the second image both the selected and un-selected colors have been changed.

TIP: The Star Rating Control is selected by selecting the [More...] item in the UX toolbox (in the Data Controls section).

Application Server for IIS - Publishing  - IIS publish now supports optimized publishing (like all other publishing types when using the standard server). Previously, when you published to IIS all of the files in your project were automatically published. It was not possible to publish a single file, of a selected subset of files, as is possible when publishing to the Alpha Anywhere server.

When you publish to IIS, a staging folder named __staging.staging is now located in the web project folder. This folder will contain the published application in a form ready to be deployed to an IIS server.
 

Application Server for IIS - Page Security - Deny by Default -  Authorization is now denied by default under IIS. The authorization rules for accessing files under IIS were previously set on files only known at publish time. This meant that files could be added to the web root of a published application and access would be allowed to any of these files. This changes means that a file needs to have a rule set to expressly allow or allow by group name in order for it to be accessible in an application.
 

Grid Component - Detailed Javascript Error Reporting - In V4.5 detailed Javascript error reporting was added to the Grid. This was done by defining a handler for the window.onerror event. This has caused error alerts to be displayed even when the Javascript errors are benign and caused no problem with the Grids that were run in prior versions. Now, detailed Javascript error reporting is off by default, but you can turn it on using this property:

UX Component - PhoneGap - Action Javascript - Open File with Native Application -- SQL Server Reporting Services - This action can now work with SSRS reports.

UX Component - Data Driven Forms Sample Template - The sample template showing how to create a data-driven form (first released in v4.5) has been updated to include a star-rating control.

UX Copmponet - FormView Control - Action Javascript - The Action Javascript action for FormView actions now has two additional actions:

• Set state variables
• Get state variables

State variables can be referenced in the FormView layout templates (and therefore in client-side show/hide and enable expressions) using this syntax

[temp].state.your_variable_name

Say you had a container in a FormView layout that contained several controls. You wanted to show this container if a session variable (called say myVar1) was equal to 'alpha'.

MOTE: You would, of course, need to publish the value of this session variable to the client-side by setting the Published session variables property.

Here is how you would do this:

Set the show/hide expression for the container to

[temp].state.myVar1 == 'alpha'

In the client-side onRenderComplete event, execute this code to set the FormView control's myVar1 state variable to the value of the session variable.

var myVar1 = {dialog.Object}.getSessionVariable('MYVAR1');

{dialog.object}.formViewSetStateVariables('FORMVIEW_1',{myVar1: myVar1});

Watch Video - Part 1
Watch Video - Part 2

Download component

UX Component - Audio Player/Recorder Control - New Events - Two new events have been added to the Audio Player/Recorder

• onBeforeOverwriteRecording - fires if the control already has an existing recording and the user clicks the record button to get in recording mode. If there is an existing recording, the recording will get overwritten. This event will allow you to prompt the user if they really want to overwrite the existing recording. If the event returns false, the new recording is aborted.
• onAbortOverwriteRecording - fires if the user aborts a new recording.

UX Component - window.onerror Event Handler - In V4.5, the UX component generates a widow.onerror event handler to report Javascript errors. This event handler displays an alert with a full stack. In some cases, where you are loading 3rd party Javascript libraries, that might throw benign errors on loading, you might want to suppress this error reporting.

The Capture detailed Javascript error information property allows you to turn off detailed Javascript error reporting.
 

UX Component - Templates - Localize PhoneGap Application - A new template is available showing how you can localize a PhoneGap application at run-time, allowing the user to select the language used for the app. The template is called MobileAppFramework_Client-side-Language_Translation.
 

Watch Video - Part 1
Watch Video - Part 2

Download component

 

UX Component - Templates - SecurityFramework-LoginComponentMobileApp-Persistent Login - The template showing how to build a mobile app that has a persistent login has been updated. The template now applies security settings when the component is reloaded and a persistent login token is found.

Alpha Anywhere Application Server for IIS - Publish - Delete Files - Publish to IIS no longer deletes files and folders that are not part of the web project. This applies to existing publish profiles and new publish profiles. Previously, any files in the target webroot folder that were not part of the web project were deleted when a project was published.

In the event a you want the old delete behavior, the Delete existing files option can be checked in the publish profile:

or the Delete existing files option can be checked in the Advanced Settings section when creating a new publish profile:

UX Component - Pre-Defined Date Range Selector Control - The Date Range selector control is useful if your UX component has controls where the user must enter a start date and an end date.

In the image below, the Date Range Selector (a dropdown box) shows the list of date ranges. The user has selected the 'This Year-to-date' range and the two input controls (one for date start, the other for date end) have been filled in.

To add a Date Range Selector control to your UX, select the control from the Defined Controls section of the UX toolbox.

Once you have added the control, you must edit the Javascript in the control's onChange event to define the Ids of the start and end date controls.

The Choices property for the Date Range Selector shows these choices. These are the built in options. You can add text or language tags to the display value if you want to show the choices in a different language.

|
Today|today
Yesterday|yesterday
This Week|thisweek
This Week-to-date|thisweektodate
This Month|thismonth
This Month-to-date|thismonthtodate
Last Week|lastweek
Last Month|lastmonth
Next Month|nextmonth
This Year|thisyear
This Year-to-date|thisyeartodate
This Quarter|thisquarter
This Quarter-to-date|thisquartertodate
Last Quarter|lastquarter
Next Quarter|nextquarter

You can also add your own custom choices to this List. When you define a custom choice you use this syntax

Display value|javascript:javascript code to compute start and end date

The Javascript code that you write must follow these rules:

• the code must fit on a single line -- therefore be sure to use semi-colons to terminate all statements
• the code must not contain any commas - as commas are interpreted to have special meaning when the dropdown list is computed.
• the code must return an object with two properties: startDate and endDate.

For example, here is how a customer item called 'Tomorrow' could be added to the choices in the Date Range Selector Control:

(Code shown on multiple lines for clarity. Must all be on a single line)

Tomorrow|javascript:/*custom date range. code must not contain any commas*/var d1 = new Date(); var d2 = new Date(); d1.setDate(d1.getDate() + 1); d2.setDate(d2.getDate() + 1); var obj = {}; obj.startDate = d1; obj.endDate = d2; return obj;

Xdialog - Overlays - You can now design Xdialogs with floating 'overlay' windows. The overlays are similar to bubble-help that you can define for toolbar buttons, Xdialog buttons, etc. except that the overlay content can be any HTML text and the overlay can be applied to any part of the Xdialog.

In the images below an overlay is shown when the mouse if over the combo box and another overlay is shown when the mouse is over the button.

The Xdialog {overlay=variableName} directive is used to define an overlay.

Here is the code to produce the above Xdialog.

dim overlay1.html as c = <<%html%
<div style="margin: 0px; padding: 5px; border: 1px blue solid; border-radius:10px;">
This <b>combo</b> lets you pick a number on entries<br>
Your choices are one, two, three or four.
</div>
%html%

dim overlay2.html as c = <<%html%
This is the button that performs the action
%html%

dim item as c = "one"

ui_dlg_box("with_help",<<%dlg%
A Combo;
List {overlay=overlay1}[.60item^={one,two,three,four}];
{line=1};
{overlay=overlay2}
<&Do It...>
%dlg%)

UX Control - Multi-select Tokens Control - Text Highlighting - When you start typing into a multi-select tokens control, the list of choices that is displayed, which is filtered, by the text you have typed, now shows the matches in the choice list with the text you have typed in bold.

For example, in the image below, the user has typed an 'a' and the choice list shows all of the items that contain an 'a'. Notice that in the choice list all of the 'a' characters are bolded.

If you have an existing multi-select token control you will need to edit and resave to get this feature.

ViewBox and FormView Control - Post-process event - You can now specify post process Javascript for each Layout. The post process Javascript runs after the HTML for the layout has been rendered. You can use the Post-process event to modify the HTML that is shown in the layout. A common use of this event is using the A5.u.html.highlight() function to highlight some text in the Layout html.

Javascript Library - A5.u.html.highlight() Function - Can be used to add markup to an HTML string to highlight portions of the text in the HTML. Any text in HTML elements or attributes is ignored.

Syntax:

A5.u.html.highlight(html, searchString [, prefix [,suffix]])

Where

• html is the html text you want to search in
• searchString is the text you are searching for
• prefix - optional text to add before any matches - if prefix and suffix are omitted then the matches are wrapped in span tags that set the font-weight to bold. prefix can also optionally be a function that takes these arguments: search, match, offset, html
• suffix - optional text to add after any matches

Example

var html = '<div>this is some text</div>';
var html2 = A5.u.html.highlight(html,'ome')
 

The resulting html2 string will be:

<div>this is s<b>ome</b> text</div>

Example using a function for the prefix argument:

count = 0;

var html = '<span>this text is inside a span. But only a single span</span>'

A5.u.html.highlight(html,'span',function(search,match,offset,html){
    count++;
    return '<i id="match.'+count+'">'+match+'</i>';
    }

)

Result

<span>this text is inside a <i id="match.1">span</i>. But only a single <i id="match.2">span</i></span>
 

Grid Component - Pre-defined Date Ranges - When you define the Search Part for a Grid, you can specify that any of the search fields are 'range' searches. If you turn on the range search feature, the Search Part will display two search fields for the start date and the end data.

You can now also display an optional pick list to select common date ranges, as shown in the image below. If you select one of the pre-defined date ranges, the dates in the From and To input controls will be filled in.

To turn on the pre-defined data range feature, check the Pre-defined date range selector property.

You can then click the smart field for the Pre-defined date range selector settings control to configure the selector.

The settings dialog allows you to set:

• width of the control
• label to show above the control
• in-line style for the control
• class name for the control
• list of pre-defined date ranges shown in the control.

By default a standard set of pre-defined date ranges are shown. These are:

• Today
• Yesterday
• This Week
• This Week-to-date
• This Month
• This Month-to-date
• Last Week
• Last Month
• Next Month
• This Year
• This Year-to-date
• This Quarter
• This Quarter-to-date
• Last Quarter
• Next Quarter

If you want to translate these names into different languages you can customize the list of choices and add language or text dictionary tags to each label.

You can augment this list with your own data ranges, or you can replace the built-in list with your own date ranges.

To define your own entry to appear in the list of choices, add a choices to the choice list that is defined as follows:

display name in the selector|value|javascript

where value is a unique name for the selection. The value must not contain any special characters or spaces. Javascript is some code that returns an object with two properties: startDate and endDate.

For example:

a5_ink_to_png() Function - This function now has a new parameter that lets you control how the image is created from the ink. Previously, the image was bound to the size of the ink with a 20px border. Now you can size the image to the entire ink page, not just the bounds of the ink text.

The new optional parameter is flagUseViewBox. This defaults to .f. (size the image to the bound of the ink). Set to .t. to size the image to the entire ink page.

Syntax:

a5_ink_to_png(c ink ,n heightInPoints,n widthInPoints,c filename ,l   flagUseViewBox)
 

Videos

Security

Alpha Anywhere Server for IIS - A potential security issue under IIS has been fixed. A UX AJAX request could be crafted to return the content of a file that should not be visible outside of the server. This fix closes this vulnerability.

Features

email_send_sparkPost() Function - Reply To - Support has been added for the 'Reply to' parameter.

Example:

dim ms as p
ms.send_to = "Fred@acme.com"
ms.reply_to = "Harry@acme.com"
ms.from_email = "admin@acme.com"
ms.from_alias = "admin@acme.com"
ms.from_name = "Admin" 
ms.subject = "Reply To Now Supported"
ms.message_html = "Message goes here"
dim key as c = "Your api key"
pp = email_send_SparkPost(key,ms)
 

Grid Component - Column Sorting - Initial Sort Direction - When the user first clicks on a column to sort the Grid on that column an ascending sort is performed. Now you can specify that the initial sort should be descending.

UX Component - Minimum Build Number - You can now specify a minimum build number for a UX component. If a developer tries to edit the component using a build that is older than the specified minimum build, a warning will be displayed. The user will not, however, be prevented from editing the component.

UX Component - Data Driven Forms Sample Template - A new sample template has been adding showing a technique for implementing data driven forms. A data driven form is a form where the fields in the form are determined at run-time, rather than at design-time.

Watch Video - Part 1
Watch Video - Part 2
Watch Video - Part 3
Watch Video - Part 4

Download component

Typically, the form is generated by first querying a database to determine what fields the form should display. Then, some Xbasic code is executed to generate a dynamic form definition.

In the example template the form is implemented using a ViewBox control, an Editor Set and numerous Editors for editing the field values shown in the form.

The image below shows how the sample component renders a particular data-driven form. The actual fields shown in the form are easily controlled by editing a JSON object that defines the fields, the field types and the editor to be used to edit the field value.

UX Component - Multi-select Token Control - A new control type is available for the UX component. The Multi-select Token control is similar to the Edit-combo control and the Auto-suggest control. However, the selected values are displayed as 'tokens' (as shown in the image below where 'Belgium', 'Brazil' and 'Canada' are selected).

Watch Video - Part 1
Watch Video - Part 2

Download Component

The user can select values from a pick list as shown in the image below. The pick-list can be automatically displayed when the user starts typing in the input control, or can be displayed when the user clicks on the down array (which is optionally displayed). The user can also select tokens by typing the value into the control and then pressing the Enter key.

To delete a previously selected token, click on the X icon in the token, or click to the right of the last selected token and press the Backspace key.

The choices for the pick-list can be statically defined, can be derived from querying a SQL database, or can be computed by an Xbasic function.

How to Add a Multi-select Token Control to a UX Component

To add a Multi-select Token control to your UX component, select the [More...] item in the Data Controls section of the UX toolbox.

The Multi-select Token control is a Data Control. This means it has a .getValue() and a .setValue() method, just like other Data Controls. When the UX is submitted, the data in the Multi-select Token control are submitted as a comma delimited list of token values.

For example, if there are three tokens selected with values of 'USA', 'UK' and 'Canada', the value submitted is 'USA,UK,Canada'

To set the value in a Multi-select Token control you must specify an array of values. For example

{dialog.object}.setValue('MY_MULTISELECT_TOKEN_CONTROL',['USA','UK','Canada']);

To set a default value for the control in the Default value property in the property sheet you can use this syntax

array(USA,UK,Canada)

Setting the Multi-Select Token Control Properties

To set the properties of a Multi-select Token control, click the smart field for the Control properties property in the Property sheet.

The configuration genie window is displayed, as shown below:

• Method for defining choices - Allows you to specify how the data for the choices displayed by the control are obtained. You can enter a static list of choices, you can specify a SQL query, or you can specify an Xbasic function that will compute the choices. If you specify a SQL query then you must either specify the name of the table that will be queried, or you can specify your own SQL statement (which could be a call to a stored procedure).
  
  In the case where you select the FieldsFromTable option, you must specify at least two columns from the table. The first column (Value column) contains the value that the selected token will have (i.e. just like a Dropdown box, each choices has both a Display property and a Value property - The Display property defines what is displayed in the choice list and the Value property is the actual value of the token). You can also specify an optional 3rd column - List Display column. This property defines the display value shown in the choice list. If you do not specify this property, the choice list shows the Display property of each choice.
  
  In the case where you specify an explicit SQL statement, your query must return a result set with either 2 or 3 columns. The first column must have a name of 'value', the second column must have a name of 'display' and the optional 3rd column must have a name of 'listDisplay'. For example:
  
  SELECT contactname as value, customerId as display from Customers
• Display icon to open choice list - when the user begins to type in the control, the choice list is opened and is filtered on the text the user has typed. This is similar to how an auto-suggest control works. However, you can also specify that an icon should be displayed (either to the right or left of the control) that the user can click on to show the choice list.
• User must select from choices - If un-checked, the user can type in any value into the control. When the user presses  Enter the text the user has typed is added to the token list. If this property is checked, if the user types in a value and then presses Enter and the text the user has typed is not in the choice list (i.e. is not the value property for one of the choices in the list), a new token is not added.

• Icons - You can customize the icons used to display the choice list and to delete a previously selected token, but you must select SVG icons.
• Token CSS type - can be either Default or Custom - allows you to customize the appearance of the displayed tokens. If you select Default, you can set the tokens to have square or rounded borders by setting the Token border style property. In the images above, the border style has been set to rounded.
• onChange - you can specify Javascript code to run when the value in the control changes. This event will fire each time the user makes a selection from the choice list to select a new token, or when the user types in the value of a new token and presses Enter, or when the user deletes a token. Your code can reference this.value, an array of the selected token values.
• valueNotInList - you can specify Javascript code to run when the user enters a value that is not in the list of choices. This property is only shown if the User must select from choices property is false. If the user types in a value and then presses Enter, if the value the user typed in is not in the list of choices, the code defined for this event will execute. You can use this event to add the value the user typed into a database.

Dynamically Populating Choices at Runtime

You can dynamically populate the choices in the Multi-select Token control at runtime by calling the control's .populate() method. For example, assume you have a Multi-select Token control called 'MST1'. You can use the following Javascript  to populate the control's choices:

var _d = {
    "data":[
        {"value" : "Argentina", "display" : "Argentina"},
        {"value" : "Austria", "display" : "Austria"},
        {"value" : "Belgium", "display" : "Belgium"},
        {"value" : "Brazil", "display" : "Brazil"},
        {"value" : "Canada", "display" : "Canada"},
        {"value" : "Denmark", "display" : "Denmark"},
        {"value" : "Finland", "display" : "Finland"},
        {"value" : "France", "display" : "France"},
        {"value" : "Germany", "display" : "Germany"},
        {"value" : "Ireland", "display" : "Ireland"},
        {"value" : "Italy", "display" : "Italy"},
        {"value" : "Mexico", "display" : "Mexico"},
        {"value" : "Norway", "display" : "Norway"},
        {"value" : "Poland", "display" : "Poland"},
        {"value" : "Portugal", "display" : "Portugal"},
        {"value" : "Spain", "display" : "Spain"},
        {"value" : "Sweden", "display" : "Sweden"},
        {"value" : "Switzerland", "display" : "Switzerland"},
        {"value" : "UK", "display" : "UK"},
        {"value" : "USA", "display" : "USA"},
        {"value" : "Venezuela", "display" : "Venezuela"}
    ]
};

var obj = {dialog.object}.getControl('MST1');
obj.populate(_d);

Grid Component - Summary Fields - Headers - You can now specify that column headers should be repeated before the summary values are shown (as shown in the image below). This is useful when you have a Grid with a lot of rows and the page must be scrolled to get to see the summary values.

To turn on this feature, check the Repeat column headings above summary values property.

Web Security - Get User Values When Using Active Directory - a5ws_GetUserValuesActiveDirectory()  - A function named a5ws_GetUserValuesActiveDirectory() has been added to Alpha Anywhere.  It can be used in code running on a web server to get user values when using Active Directory for security authentication.  This function works in the Classic Alpha Anywhere server and IIS and retrieves a number of default values from Active Directory.  Help about this function is found in the documentation at 

https://www.alphasoftware.com/documentation/index?search=api%20a5ws%20getuservaluesactivedirectory%20function

Xbasic - Arrays - .push() method - A new .push() method has been added for Xbasic arrays. To push onto a property array use JSON syntax to define the object you want to push onto the array. See examples.

Examples:

dim arr[0] as c
arr.push("hello")
arr.push("world")
? arr
= [1] = "hello"
[2] = "world"
 

'using a property array
dim arrp[0] as p
 

'push object defined using JSON syntax onto the array
arrp.push({"text":"hello"})
arrp.push({"text":"world"})
? arrp.size()
= 2
? arrp[1].text
= "hello"
? arrp[2].text
= "world"

UX Component - List Control - Inject Arbitrary Headers and Footers into List Data - You can now inject arbitrary headers and footers into List data using the onBeforeListDraw event. For example, in the image below a header is inserted for each group of 3 rows of data. A footer is also inserted. Both the header and footer can contain arbitrary HTML. As shown in the image, the footer text contains some bold text as well as a SVG icon.

Watch Video
Download Component

Using items (i.e. the a5-item attribute), you can add event handlers to the header and footer text (see video).

The onBeforeListDraw event allows you to return a new array containing the data to be rendered in the List.

In the above example, the following Javascript is defined in the onBeforeListDraw  event to add the headers and footers to the List.

var ta = [];
var group = 1;
for(var i = 0; i < data.length; i++) {
    //add a user defined title into the data before every 3rd row
    if( (i % 3 ) == 0) {
        if(i != 0) {

            //add the footer html
            ta.push({'*static': '<div a5-item="item1:'+(group-1)+'" style="padding: 10px; border: solid 1px gray; border-radius: 10px;">

                    <img src="svgIcon=#alpha-icon-basketFull:26{ fill: #2730d1; stroke: #f52d2d;}" />This is some static <b>HTML</b>.

                    It shows how you can add arbitrary HTML into the List</div>'});
        }

        //add the header html
        ta.push({'*title': 'Group ' + group});
        group++
    }
    ta.push(data[i]);

}
//return a new array of data to be used to draw the list
return ta;

To inject a header into the List, add an object into the data array that has a '*title' property name. To add arbitrary HTML (e.g. a footer), add an object into the data array that has a '*static' property name.

Notice that in the above Javascript code, the data array is passed in. But the contents of this array are not modified. Instead a new array (called ta) is created and the Javascript returns this array. The List is then rendered using this new array of data.

Collapsible Headers

The image below shows a slightly more complex example. In this example, each header is made collapsible. For example, Group1 through Group4 have been collapsed. Tapping anywhere on the header will toggle the collapsed state of the group.

Download Component - collapsible headers

The Javascript in the onBeforeListDraw event to accomplish this is shown below:

var ta = [];
var group = 1;
var to = this._to;
if(typeof to == 'undefined') to = {};
var flag;
var iconOpen = A5.u.icon.html('svgIcon=#alpha-icon-addCircleBorder:icon,24');
var iconClose = A5.u.icon.html('svgIcon=#alpha-icon-removeCircleBorder:icon,24');;
var icon;
for(var i = 0; i < data.length; i++) {
//add a user defined title into the data before every 3rd row
    if( (i % 3 ) == 0) {
        if(i != 0) {
            if(flag == 'opened') {
                ta.push({'*static': '<div a5-item="item1:'+(group-1)+'" style="padding: 10px; border: solid 1px gray; border-radius: 10px;"><img src="svgIcon=#alpha-icon-basketFull:26{ fill: #2730d1; stroke: #f52d2d;}" />This is some static <b>HTML</b>. It shows how you can add arbitrary HTML into the List</div>'});
            }
        }

        flag = to['Group:' + (group)];
        if(typeof flag == 'undefined') flag = 'opened';
        if(flag == 'opened') icon = iconClose;
        else icon = iconOpen;
        ta.push({'*title': '<div a5-item="toggle:' + group + '" style="line-height: 26px;"><div style="float:right;">'+icon+'</div>Group'     +   group + '</div>' });
        group++
    }

    if(flag == 'opened') {
        ta.push(data[i]);
    }
}
return ta;

Notice that the header is wrapped in a div that has an a5-item attribute called toggle. Notice also that the list contains a variable called _to that contains an object with the open/closed state of each group. If a group is closed then the code that pushed the list data onto the new array (ta.push(data[i]) is skipped over, thus omitting these rows from the rendered List.

When a user taps on a header, the onClick event in the toggle item is fired. This event will then add the group's open/closed state to the List object's _to variable. The Javascript code in toggle item's onClick event is shown below:

var to = lObj._to;
if(typeof to == 'undefined') to = {};
var flag = to['Group:' + ia];
if(typeof flag == 'undefined') {
    to['Group:' + ia] = 'closed'
} else {
    if(to['Group:' + ia] == 'closed') to['Group:' + ia] = 'opened';
    else to['Group:' + ia] = 'closed';
}
lObj._to = to;
lObj.refresh();

UX and Grid Components - Amazon S3 - V4 Signing - Ohio Region - Amazon has changed the way that URLs must be signed for their newer regions. For example, support for the Ohio region was recently added to the Storage Connection String builder. But in order to upload or download files to/from the Ohio region, URLs must be signed using Amazon's V4 signing scheme. Support has been added for V4 signing, so now uploads and downloads to the Ohio region will work correctly.

UX Component - ExpandingMenu Control - A new control type is available in the UX Component. The Expanding Menu control displays a list of menu choices, some of which may have sub-choices (indicated by an icon at the right edge of the item). When a menu item is clicked, it can invoke Javascript code. If the menu has a sub-menu, the sub-menu is shown using animation.

In the image below the ExpandingMenu is shown in its full collapsed state and it a partially expanded state.

To add an ExpandingMenu control to your UX component, select the [More...] item in the Data Controls category.

NOTE The ExpandingMenu is in the Data Controls section, because, like all Data Controls, it has a {dialog.object}.setValue() and a {dialog.object}.getValue() method. The 'value' of the current selection in the Expanding menu is defined by the 'value' property for each node in the tree (see below).

Then select the ExpandingMenu option from the dialog.

To configure the ExpandingMenu control, click the smart field for the Control properties property.

This will bring up a genie where you can define the choices shown in the ExpandingMenu and also set other properties.

To define the choices and sub-choices shown in the menu click on the smart field for the Menu data genie property.

This will bring up a dialog where you can type in your menu choices, using tab indents to indicate which menu choices are sub-choices.

For example, in the image below, the top level menu choices are:

item1

item2

item3

item4

Item1 and item2 hav3 sub-choices.

When you close the Add Item dialog, the Tree Data Genie is shown (see image below). This dialog allows you to set properties for each menu item in menu tree.

Properties that you can set include:

• Item - The HTML text show in the menu
• Icon - an optional icon shown to the left of the menu text
• Value - an optional value that indicates what the value of the ExpandingMenu control will be if this menu item is selected. Also, if the .setValue() method is used to set the value of the ExpandingMenu control, you will need to set the control to a value defined in the Value property.
• Security groups - if using the Security Framework- the security groups that can see this menu item. If a menu item is hidden because it is not in the specified security group, the menu item and all of its children are hidden.
• Server-side show/hide expression  - An expression that is evaluated server-side to determine if the menu item should be shown. Server-side show/hide expressions typically involve session variables. Enter an expression that evaluates to .t. or .f.
• Client-side show/hide Javascript - Javascript code that returns a true or false value. If the code returns false, the menu item (and all of its children) are now shown.

Grid Component - Delete Checkbox - Delete All - A new option has been added to the Grid component to allow you to check/uncheck the Delete checkbox in all rows on the current Grid page at once.

To turn on this feature, check the Allow 'delete-all' checkbox property.

Update Settings

The Grid will be rendered as shown below. The Delete column title will have a checkbox in it. Checking this box will check the delete checkbox in all Grid rows on the current Grid page.

UX and Grid Components - Javascript Errors - Error Reporting - Error reporting when a Javascript error occurs has been improved. The error message will now include a stack dump.

UX Component - ViewBox Control - Sample ViewBox - When you create a new ViewBox a new sample ViewBox is is now available when you click on the Load Sample ViewBox hyperlink.

The Menu tree option displays an hierarchical menu as sown in the image.

UX Component - Sample Templates - MobileAppFramework_with_SplitView_ExpandingTreeMenu - A new sample template for mobile apps is available. This template is similar to the the MobileAppFremework_SplitView_Hierarchical_Menu template, except that the menu is rendered using a ViewBox control, not a List control.

The ViewBox menu can contain nested menus. When a menu item that has children is expanded, the ViewBox is animated, creating a very appealing visual effect.

To use the template, chose the template from the list of available templates when you create a new UX component.

On a Phone, the UX will render as shown below.

Tapping on the 'hamburger' menu icon will show the menu in its collapsed state:

You can expand various branches of the menu. When you tap on a menu item that is an endpoint, the associated action for that menu item is executed.

On a tablet, the menu is always shown on the left of the screen.

To edit the list of choices shown in the menu, edit the ViewBox Control. In the ViewBox control, edit the Data Source. The menu structure and the associated menu actions are defined in the Javascript object for the ViewBox data source.

The background color of the menu is set in the CSS tab in the ViewBox builder. To change the menu color, edit the ViewBox and in the CSS tab, edit this value:

$color: #221f22; //this sets the color of the menu tree.
 

Xdialog - Simple List View Control - The simple list view control has been enhanced to allow sortable columns and different views of the data.

In the image below, the List has been sorted on the Firstname column and a small icon in the column title indicates the sort direct.

This is the 'report' view of the data.

In the image below, the 'list' view of the data is shown.

In the image below, the 'SmallIcon' view of the data is shown.

To indicate that a column is sortable, add a caret to the column definition. For example:

[%M;K;%.100,20id^"Firstname:30^|Lastname:50^"list!idchange];
 

In the above example, we have defined both the Firstname and Lastname columns to be sortable.

You can specify if the sort should treat the data as numeric or data/time values by adding a suffix of N or T after the ^. For example

[%M;K;%.100,20id^"Lastname:30^|DateOfBirth:50^T"list!idchange];
 

To change the view of the List, send a command to the list using the ui_dlg_ctl_command() function, as shown in the example below. The second parameter in the function is any string in the control definition that uniquely identifies it. In the example below, the text string 'idchange' is used to identify the control.

You can also sort the List on multiple columns using the ui_dlg_ctl_command() function. For example to sort on Lastname (column 2) and then Firstname (column 1), you this command:

 ui_dlg_ctl_command(dlg_title,"idchange","sort:2,1")

Full example:

dim list as c
list = <<%txt%
{image=$$generic.orb.green}Erica|Jones
{image=$$generic.orb.blue}Tom|Snider
{image=$$generic.orb.yellow}Molly|Maloney
%txt%
list = replicate(list,30)
list = *for_each(x,"{data=" + *index() + "}" + x, list)


dim dlg_title as c = "Quick ListView - Sortable"
ui_dlg_box(dlg_title,<<%dlg%
{wrap=100}
This dialog shows a simple ListView using the new ^" Xdialog syntax.;
Using this technique, it is possible to create a simple ListView with substantialy less Xbasic than the {{Listview} Xdialog command.;
The ^ in the control definition makes the column sortable.;
 

[%M;K;%.100,20id^"Firstname:30^|Lastname:50^"list!idchange];
{lf};
Click button to change List layout;
<List><Report><SmallIcon>
%dlg%,<<%code%
if a_dlg_button = "List" then
    a_dlg_button = ""
    ui_dlg_ctl_command(dlg_title,"idchange","list")
else if a_dlg_button = "report" then
    a_dlg_button = ""
    ui_dlg_ctl_command(dlg_title,"idchange","report")
else if a_dlg_button = "smallicon" then
    a_dlg_button = ""
    ui_dlg_ctl_command(dlg_title,"idchange","SmallIcon")
else if a_dlg_button = "idchange" then
    a_dlg_button = ""
    ui_msg_box("Note","User clicked on : " + id )
end if
%code%)

UX Component - FormView Control - Pre-defined Editors - AlphaNumeric KeyPad Editor - A new pre-defined editor for editing character and numeric values in a FormView control (without using the Native keyboard on a mobile device) has been added.

The editor, as shown in the two images below, display the AlphaNumeric KeyPad editor in its two possible configurations. In the first image, the KeyPad is shown as it would be displayed on a Phone.

In the second image, the KeyPad is shown as it would be displayed on a Tablet.

To add the editor to a UX component, select the [Editor-AlphaNumericKeyPad] from the Defined Controls section of the toolbox.

To configure the keypad settings, click the smart field for the Editor configuration genie property in the FormView builder.

The genie allows you to configure various aspects of the keypad.

UX Component - FormView Control - Pre-defined Editors - Time Value Editor - A new pre-defined editor for editing time values in a FormView control has been added.

The editor, as shown below, displays SpinList controls for the hour, minutes and AM/PM values.

The editor also displays a button to set the selection in the SpinList controls to the current time.

You can configure the editor to hide the 'Now' button.

To add the TimeSpinLists editor to a UX component, select the [Editor-TimeSpinLists] item in the Defined Controls section of the UX toolbox.

To configure the Time value editor, click the smart field for the Editor configuration genie property in the FormView builder on the Fields tab.

The configuration genie allows you to specify if the 'Now' button should be shown.

UX Component - FormView Control - Pre-defined Editors - Date/Time Value Editor - A new pre-defined editor for editing date/time values in a FormView control has been added.

The editor, as shown below, displays SpinList controls for the month, day, year, hour, minutes and AM/PM values.

The editor also displays a button to set the selection in the SpinList controls to the current date and time.

You can configure the editor to hide the 'Now' button and to show a 'Clear' button which 'un-sets' the date/time value.

To add the DateTimeSpinLists editor to a UX component, select the [Editor-DateTimeSpinLists] item in the Defined Controls section of the UX toolbox.

To configure the Time value editor, click the smart field for the Editor configuration genie property in the FormView builder on the Fields tab.

The configuration genie allows you to specify if the 'Now' button should be shown.

UX Component - FormView Control - Pre-defined Editors - Numeric Keypad Editor - A new pre-defined editor for editing numeric values in a FormView control has been added.

The editor, as shown below, displays a keypad that allows the user to enter numbers. When editing a value using the numeric keypad, the native keyboard on a mobile device is not used.

A configuration genie allows you to specify various settings for the keypad.

To add the Numeric KeyPad editor to a UX component, select the [Editor-NumericKeypad] item in the Defined Controls section of the UX toolbox.

To configure the Numeric KeyPad  editor, click the smart field for the Editor configuration genie property in the FormView builder on the Fields tab.

The configuration genie (shown below) allows you to configure various settings for the keypad.

The Custom formatting Javascript allows you to define code that formats the number when it is displayed in the Keypad number display area.

For example, in the image below, the number is formatted to display a $ sign and two decimal places.

To achieve this, the Custom formatting Javascript property was defined as:

return Number(val).toFormat('$#,##0.00;$ (#,##0.00);------');

UX Component - ControlBar Control - Disclosures - Injectible Content - When you create a Disclosure in a ControlBar you can now set the Disclosure type to Injectible Container.

Previously, you could add a special Injectible Content placeholder in the HTML that you defined for the Disclosure. Setting the Disclosure type to Injectible Container is easier than using Injectible Content placeholders in the HTML and it has another advantage -- it makes it very easy to display List controls in the disclosures displayed by the Control Bar.

Watch Video - Part 1
Watch Video - Part 2

Download Component

CSS - Shared Styles - You can now define CSS styles that are shared across all stylesheets. Shared styles can be defined at the system level or at the project level.

The shared styles are stored in the following locations:

• [Executable Folder]\css\_sharedStyles - this is where system level shared styles are defined. These styles are typically defined by Alpha Software, not the developer.
• [Project Folder]\css\_sharedStyles - this is where project level shared styles are defined.

The shared styles are defined in a file called style.sass in the _sharedStyles folder. The shared styles can include SASS definitions.

For example, if you define a CSS selector called .style1 in the [Project Folder]\css\_sharedStyles\style.sass file, this selector will be available in all components, regardless of what stylesheet the component uses.

UX Components - ControlBar Control - Disclosure Buttons - Margins -  You can now specify margins for the content that is displayed in a ControlBar disclosure.

For example, in the image below, the List in Window disclosure button in the ControlBar in the UX footer displays a disclosure and sets the top, bottom, left and right margins to constrain the size of the disclosure content, giving the impression that the List is displayed in a window.

AlphaLaunch - AEX Files -  When you register a UX component as an AlphaLaunch App you can now specify that .aex files for this App should be compiled and published.

Xdialog -WaitDialog - You can now set the width of the Xdialog Waitdialog.

Example:

dim p3 as waitdialog
p3.create(3,"bounce",500) 'set with width to 500
p3.set_color("dark green")
p3.Set_Bottom_Message("This is the bottom row message - line1." + crlf() + "Line2")
p3.Set_Message("This is the top row message.")

'to close the waitdialog

p3.close()

UX Component - List Control - Allow Any Value - The List control now has a new property, Allow any value, that allows you to set the List value to a value not in the List data. If this property is not checked (the default), you cannot set the List value to a value that is not in the List data.

UX Component - Defined Control - Time Editor for FormView Control - A new pre-defined editor for a time value in a FormView control is available.

To select the time value editor, select [Editor-TimeSpinLists] from the list of controls in the Defined Controls section.

The image below shows a form control on the left with a time value and a time value editor on the right. The time value editor is implemented using three spin lists - one for hours, one for minutes and one for AM/PM.

You can modify the values in the hours spin list if you want to user to select minutes in multiples of 5, 10, 15 minutes, etc.

AlphaLaunch - Download Applications from S3 - By default, when you publish an App to AlphaLaunch, the AlphaLaunch client (i.e. the App running on the mobile device) will download the App from the same folder to which the App was published. The App will be published to a folder in the webroot of the standard Alpha Anywhere server, the Alpha Anywhere IIS server, or AlphaCloud.

However, you can also publish the app to a S3 bucket and when the AlphaLaunch user tries to install a new App, the App files will be downloaded from S3, rather than from your Alpha Anywhere server. Of course, once the user actually starts using the App on their device, Ajax callbacks will be handled by your Alpha Anywhere server.

The benefit of downloading Apps from S3 is that you offload work from your Alpha Anywhere server to S3. Also, in certain cases, when using an Android device and downloading an App from an Alpha Anywhere standard server, the install might fail because the App has too many files. By using S3 as the download location, you can circumvent this problem.

If you want to publish the App to S3, check the Use Amazon S3 as download site for AlphaLaunch Apps checkbox on the Publish to AlphaLaunch dialog.

You will need to specify:

• S3 URL - this is the URL to your S3 bucket where your AlphaLaunch files will be published. e.g. http://alphalaunchservers.s3.amazonaws.com/. Do not include the name of the S3 Folder in the URL
• S3 Folder - the folder within the S3 bucket where your App files will be published
• S3 Connection String - the connection string to your S3 bucket. You can either use an explicit or named connection string. If using a named connection string, you must use the ::storage:: prefix.

Xbasic - SQL Server Reporting Services - a5w_report_saveAs() Function - You can now use the a5w_report_saveAs() function to print SSRS reports.

Syntax

c filenameOut = a5w_report_saveAs(c reportname, c type, c filter, c order, c filename,P globalVariables , P printOptions, sql::arguments Args)

Where

• filenameOut - the filename where the report output is stored. Generally will be the same as filename (the passed in filename), unless the file extension had to be changed.
• reportname - the name of the SSRS report (e.g. customersbystate.ssrs.a5rpt)
• type - the output type. Supported types are PDF, EXCEL, WORD, HTML, rtf
• filter - the client side filter - not supported for SSRS reports - must be set to a blank value
• order - the client side order - not supported for SSRS reports - must be set to a blank value
• filename - the filename for the output report (actual filename used is returned in filenameOut)
• globalVariables - not supported for SSRS reports - must be set to null_value()
• printOptions - not supported for SSRS reports - must be set to null_value()
• Args - sql::arguments with argument values for the SSRS parameters

Example:

dim reportName as c
reportName = "customersbystate.ssrs.a5rpt"


dim args as sql::Arguments
args.add("whatcountry","UK")
 

dim filename as c

filename = a5w_report_saveAs(reportname,"pdf","","","c:\pdf\report1.pdf",null_value(),null_value(),args)
sys_open( filename)

 

UX Component - List Control - Detail View - Incremental Refresh After List Populate - A pattern that some mobile App developers use when building offline applications is to automatically do an incremental List refresh when the App is first loaded. This ensures that the user has up to date data on their device. An incremental List refresh (rather than a full refresh) is done so that any unsynchronized edits are not lost. There was no obvious event in which the incremental refresh could be triggered, especially if the List had been configured to download media files to the filesystem.

Therefore, to make this pattern easy to set up, a new property has been added to the List. The Do incremental refresh after List is populated property will allow you to kick off an incremental refresh of the List after the List has been populated.

UX Component - Action Javascript - File Upload Action - S3 Timeout - When you upload to S3, you can now specify a timeout setting. If you are uploading a large number of files, you might need to increase this setting otherwise, you might get 'permission expired' errors from S3 indicating that the time window in which uploads are permitted has expired.

PhoneGap Applications - Usage Descriptions for Plugins -  PhoneGap Build now allows the addition of a <config-file> element into the config.xml file.

http://docs.phonegap.com/phonegap-build/configuring/config-file-element/

This lets you add xml directly to the iOS Info.plist file and Android AndroidManifest.xml file.

This solves an error that you might get when submitting an app to the Apple App Store. The error complains about certain UsageDescription strings not being set in PhoneGap Build Plugins.

E.g.

Camera Plugin : NSCameraUsageDescription

Calendar Plugin : NSCalendarsUsageDescription
 

The entry into the config.xml file to set the UsageDescription strings is:

<config-file platform="ios" parent="NSCalendarsUsageDescription" mode="replace">
    <string>This app will use the Calendar</string>
</config-file>
 

UX Component - Client-Side Events - onConnectionChange Event - The onConnectionChange event when the device either gets a connection, or looses its connections. The event has a parameter that tells you whether the device has or does not have a connection. Previously, this parameter was not always accurate. Now, it can be relied on.

A common use case for this event is to only show a 'sync' button on a mobile device when a connection is available. In addition, before executing an Ajax callback you might want to first check that the Alpha Anywhere server is responding (it is possible for the Alpha server to be offline even though the device has a connection).

In summary, here are the events and methods that you can use in a Mobile app.

• onConnectionChange client-side event - tell when when the connection status changes
• {dialog.Object}._getOnlineStatus() method - returns true/false depending on whether the device is on/off line.
• {dialog.object}.serverIsAvailable() method - calls a success callback function if the server is available - calls an error callback function if the server is not available.

Example use of .serverIsAvailable() method

var _ok = function() {
    alert('server responded');
};

var _err = function() {
    alert('server did not respond');
};
 

//wait up to 500 milliseconds before calling either the _ok or _err callback function
{dialog.Object}.serverIsAvailable(500,_ok,_err);

UX Component - List Control - <listObject>.setValue() Method - Several new options have been added to the .setValue() method.

NOTE: These new options only apply if the List is set to allow multi-selection.

• add values to the current selection
• remove values from the current selection
• toggle selected state of items in an input array of values
• select rows in a list programmatically using a passed in function that returns true/false for each row in the List
• add values that are selected programmatically to the current selection

Examples:

//adds values to the current selection
listObj.setValue({select: 'add', value : ['Smith','Jones']});

//remove values from the currently selected value
listObj.setValue({select: 'remove', value: ['Smith','Jones']});

//toggles the selected state of the items in the value array
listObj.setValue({select: 'toggle', value: ['Smith','Jones']});

//select rows in a list programmatically. If function returns true, row is selected.
listObj.setValue({select: 'match', match: function(value,data) {
        //value and data for the current row
        if(data.Country == 'USA') return true;
        else return false;

    }
   }

);

//select rows in a list programmatically. Optionally add to the existing selection
listObj.setValue({select: 'match', additive: true, match: function(value,data) {
    //value and data for the current row
        if(data.Country == 'UK') return true;
        else return false
    }
  }

);
 

UX Component - Alignment Container - Centering Content - The Alignment container allows you to easily center align content. If you have multiple controls in an Alignment container, each control is horizontally centered on its own line.

However, if you wanted (say) Control 1 and Control 2 to both be on the same line, and center align the combined width of the two controls, you can now wrap Control 1 and Control 2 in a container within the Alignment container.

UX Component - List Control - Lazy Image Loading - A new genie is available to set up a List to use Lazy Image Loading.

A common use case for Lazy Image Loading is when you have a List that displays images that are sourced from a server. If the List has a large number of rows, fetching all of the images from the server will slow down the initial render of the List. However, by implementing Lazy Image Loading, only the images for the rows that are currently scrolled into view will be fetched.

Watch Video - Part 1
Watch Video - Part 2
Watch Video - Part 3
 
Download Component

You can set a wait time that the List will wait after a row comes into view before the images for the visible rows will be fetched. This prevents fetching images for rows that you scroll past without stopping on. When a row that displays an image that has not yet been fetched is displayed, a 'waiting' image will be displayed. Once the image has been fetched, the 'waiting' image will be replaced with the real image.

To access the Quick Setup Genie, open the List control builder. Click on the Quick access... button at the bottom of the window and then select the List Quick Setup Genie menu item.

Once the Quick Setup Genie opens, select the Lazy Image Loading option.

The genie allows you to configure a number of options, such as the name of field in your List data that contains the image URL for the image to display in each row. You can also set the URL of the wait image (the image to display before the real image has been fetched).

When you exit the genie, the genie will automatically set several properties in the List, such as the onListDraw and onScroll event, the List template, etc.

AlphaDAO - oData - Authentication Options - You can now specify an Authentication option when building an oData connection string.

The options are:

• None
• Basic (the default)
• Windows Integrated

UX Component - List Control - DetailView - addTableRow() Method - The addTableRow() method allows you to programmatically add new rows to a List with a Detail View.

If you are using this method in a loop, then you can add many new rows to a List quite quickly. Under certain circumstances, this might cause a problem.

The circumstances under which this could cause a problem are:

1. The List is set to persist to storage (so that the application can function offline)
2. The List storage is set to FileSystem
3. The App is running in Phonegap.

The reason that there is a potential problem under the above scenario is that writing to the FileSystem in PhoneGap is an asynchronous operation. Each time the List is updated, the edits to the List are saved in files written to the FileSystem. But since these write operations are asynchronous, it is possible (actually likely), that the write operation for the next record added to the List will be initiated before the write operation for the current record added to the List has completed, and so on. These overlapping write operations to the FileSystem could corrupt the files used to store the List edits.

The solution to this potential problem is to temporarily suspend persisting the List while the .addTableRow() method is being called in a loop and then once the loop has completed, turn the suspension off and persist the List to storage.

To suspend persisting to the List, you set the List's .suspendPersist property to true.

To turn persisting back on, you set the List's .suspendPersist to false

To manually persist the List after you have turned suspend persist off use the List's .persistToStorage() method. You must pass in an empty object when calling this method.

For example:

//persist multiple rows in a loop

var listObj = {dialog.object}.getControl('list1');

//suspend list persisting
listObj.suspendPersist = true;

//execute the .addTableRow() method in a loop

//turn list persisting back on
listObj.suspendPersist = false;

//persist the list (passing in an empty object to the .persitToStorage() method.
listObj.persistToStorage({});
 

UX Component - Panel Navigator - Carousel Mode - If you are swiping to the left or the right to navigate from one Panel Card to another, if the Panel Card you are navigating from allows for vertical scrolling, you could easily start scrolling the Panel Card vertically while you were also swiping left or right. This creates an undesirable visual effect. Now, once you start moving the Panel Card to the left or right (to transition from one Panel Card to another), vertical scrolling the Panel Card is disabled.
 

AlphaDAO - SQLite - AlphaDAO now has built-in support for SQLite. Previously, you could connect to a SQLite database by installing an ODBC driver. However, since there was no syntax handler for SQLite, there was no support for Portable SQL or the Portable SQL functions that AlphaDAO exposes. As a result, certain operations would fail.

Now, with built-in support for SQLite, there is no longer any need to install an ODBC driver and all Portable SQL functions (with the exception of Geography functions, which SQLite does not support) are supported.

Full details on SQLite support are in the documentation.

UX Components - Checkbox and Radiobutton Controls - Render as ButtonList - Icon Alignment - A new property has been added to the builder allowing you to better control the placement of the icon relative to the text.

The Button style property has these options:

• Image followed by text
• Text followed by Image
• Text left & image right  (image will be right justified and text will be left justified)
• Image left & text right (image will be left justified and text will be right justified)

Videos

IMPORTANT: If you have UX components with Lists that have updateable Detail Views and these UX components were defined as pre-rendered then you will need to edit these components and resave them so that the pre-rendered code can be re-generated. You can use the Edit, Bulk Operations, Recalculate UX Components menu item to do a bulk update of your UX components.

If you have PhoneGap applications that use Lists with updateable Detail Views, and if you want to update the server that handles the Ajax callbacks from your PhoneGap applications, you will need to rebuild your PhoneGap applications.

Features

Xbasic - JSON - Reshape JSON - extension::JSON::FormatMapped() Method - It is sometimes necessary to 'reshape' a JSON document, changing property names, creating arrays and objects from properties, etc.

The extension::JSON::FormatMapped() method allows you to do this.

The method takes two arguments:

• a map the describes how the JSON should be reshaped. The map is itself a JSON document
• a JSON file. The JSON data to be reshaped

For example, consider the following input JSON file:

dim jsonIn as c
jsonIn = <<%str%
{
    "id" : "001",
    "fname" : "John" ,
    "lname" : "Doe",
    "address1" : "12 Main Street",
    "address2" : "Box 20"
}
%str%

Say you want to reshape this JSON document so that it looks like this:

{
    "person": {
        "id": "001",
        "firstname": "john",
        "lastname": "public",
        "address": [
            "12 Main Street",
            "box 20"
        ]
    }
}

Here is the Map that would define to achieve the above transformation:

dim jsonMap as c = <<%str%
{
    "person" : {
        "id" : "id" ,
        "firstname" : "fname" ,
        "lastname" : "lname" ,
        "address" : [ "address1" , "address2" ]
    }
}
%str%

Notice that in the input JSON, there is a flat list of properties. The firstname and lastname properties are called "fname" and "lname"

In the output document, the firstname and lastname properties are called "firstname" and "lastname", the two address fields are in an array called "address" and all of the properties are now a child of a new object called "person"

Here is how you would transform the input JSON (jsonIn) using the map (jsonMap)

dim jsonOut as c

jsonOut = extension::Json::FormatMapped(jsonmap,jsonin)

jsonOut2 = json_reformat(jsonOut) 'format the JSON

Xbasic - JSON - Flatten JSON - extension::JSON::ExtractMapped() Method - Creates a flattened JSON object from a complex JSON object. The flattened JSON object has all properties at the top level, with no nested objects are arrays.

The extension::JSON::ExtractMapped() method allows you to do this.

Assume you have a complex JSON document as shown below. Note that the only top-level property is "person"

dim jsonIn as c
jsonIn = <<%json%
{
    "person": {
        "id": "001",
        "firstname": "John",
        "lastname": "Dublic",
        "address": [
            "12 Main Street",
            "Box 20"
        ],
        "otherInfo" : {

            "x": "value of x",

            "y" : "value of y"

        }
    }
}
%json%
 

Say you want to flatten this JSON document so that all properties are at the top level and also change some of the property names. The resulting JSON document should look like this:

{
    "id": "001",
    "fname": "john",
    "lname": "public",
    "address1": "12 Main Street",
    "address2": "box 20",
    "x_value": "value of x",
    "this is the y value": "value of y"
}

Here is the Map that would define to achieve the above transformation:

dim jsonMap as c
jsonMap = <<%json%
{
    "person" : {
        "id" : "id" ,
        "firstname" : "fname" ,
        "lastname" : "lname" ,
        "address" : [ "address1" , "address2" ],
        "otherInfo" : {

            "x" : "x_value",

            "y" : "this is the y value"

        }
    }
}
%json%

Here is how you would transform the input JSON (jsonIn) using the map (jsonMap)

dim jsonout as c
jsonOut = extension::Json::ExtractMapped(jsonMap,jsonIn)
dim jsonout2 as c
jsonout2 = json_reformat(jsonout) 'format the JSON

 

UX Component - Style 'Tweaks' - When working with version 3 and above styles (these include iOS7, AndroidLight, AndroidDark, Alpha), you can now define style 'teaks'. Tweaks are adjustments to the style definition that are stored in a separate file in the Web Project folder. The adjustments include new sub-themes and CSS classes, and changes to existing sub-themes and CSS classes.

Normally when you edit a system style (such as 'Alpha'), a local copy of the style is saved in the Web Project folder and your edits are applied to the local copy of the style.js and style.sass files. The disadvantage of this approach is that if, in a future version of Alpha Anywhere, the style is changed (to fix a bug or to add support for a new control type), the changes made to the system version of style.js and style.sass will not be reflected in the local copy of these files that you created when you edited the style. You would need to manually edit the system copy of these files and copy changes to the local copy of these files. This would be complicated because it would not be easy to find the parts of the file that had changed.

On the other hand, since style tweaks are stored in a separate file, there are no local copies of the style files you are tweaking. Therefore if a future version of Alpha Anywhere updates the style, the tweaks are applied to this updated version of the style and your tweaked style will automatically have all of the changes made to the system style.

Style tweaks for a particular style are stored in this file:

<web project folder>\css\StyleTweaks\<style name>\styleTweaks.json

To define style tweaks, click the smart button for the Style sub-theme and CSS 'tweaks' property.

NOTE: If you customize the style colors and fonts using the smart field for the Customize style color and fonts property, the changes to the SASS variables that define the style's colors and fonts are also stored in the style's Tweaks file.

NOTE: You can also adjust the CSS and sub-themes in a style using these properties:

However, the adjustments made here apply ONLY to the component you are editing, whereas style 'tweaks' apply to all components in the Project that use the tweaked style.

UX Component - FormView Control - Pre-Defined Editors - TextArea - A new pre-defined editor for a FormView control is now available in the Defined Controls section of the UX toolbox. The [Editor-TextArea] pre-defined control creates an editor for a FormView value. The editor uses a TextArea control and it has a vertical scroller so that long text can easily be scrolled on touch devices.

Javascript Editor - Auto-complete for built-in Node modules - When you are editing Node Javascript code in a Javascript editor in Alpha Anywhere, you now get auto-complete for built-in Node modules. For example, assume that you enter this code into your Javascript code to get the Node filesystem module:

var fs  = require('fs')

Now, when you type

fs.

you will get auto-complete, as shown in the image below:

Node API s - The Web Control Panel now has a new category - Node APIs.

A Node API is similar to a Node Service in that they both allow you to call code written in Node from Xbasic. The difference is in how you call the code.

A Node service exposes a single piece of functionality to Xbasic. You can invoke the Node service using the node_request_result() function.

For example, assume you have a Node service called mergeData. You would call this service, passing in arguments to the service, as follows:

dim p as p

p.name = "Fred"

p.city = "Boston"

dim result as c

result = node_request_result("mergeData",p)

On the other hand, a Node API allows you to define an Xbasic class with multiple methods whose method are implemented using Node. Your Xbasic code invokes the Node code by calling methods on an Xbasic class instance. Your Xbasic code will create an instance of the class by declaring a variable of type ::NodeServices::name_of_your_Node_API and then calling methods of this class.

For example, assume you have created a Node API called myAPI and that this API exposes two methods, method1() and method2() and that each method takes a single character argument. Here is how you would invoke these methods from your Xbasic code:

'Dim an instance of the API class

dim x as ::NodeServices::myAPI

'now call methods of the class

dim result1 as c = x.method1("alpha")

dim result2 as c = x.method2("beta")

In effect, the Node API allows you to extend Xbasic with methods that are implemented using Node.

NOTE: Future versions of Alpha Anywhere will allow for another use of Node APIs. You will be able to expose REST APIs whose endpoints are implemented using a defined Node API.

How to Create a Node API

To create a new Node API, select the Node APIs category in the Web Control Panel and then click the New button.

This will open a dialog where you can name the Node API and define the methods and implementation for the API

The API methods are defined in the Definition pane (shown in the image below). The syntax used for defining the Node API methods is the same syntax used for defining an Xbasic class. Note that the Definition does not include any actual Xbasic code for implementing each method. It simply define the functions that the API will implement.

The actual implementation of the methods is coded in Node code on the Implementation pane.

The Implementation pane fills in the stub Node code to implement the API methods. You will fill in the actual code for each of the functions in the API.

When you click the Save button two files are created in the node_services folder in your Web Project

•  <node API name>.a5api file -- this file contains the definition of the Node API (i.e. the code in the Definition pane shown in the above images)
• <node API name>.js file - this file contains the Node Javascript code that implements the methods in the API.

When you edit a previously create Node API, the .js file is opened in the Alpha Anywhere Javascript editor, but the editor toolbar shows a special button (API Definition...) at the right edge of the toolbar:

The API Definition... button will bring up the Create Node API dialog (shown in the above images) where you can edit the API definition. When you exit the dialog, the the Implementation file (i.e. the .js file you are editing) will be updated to reflect the edited API definition.

Example

In this example, we will show how to create a Node API with four methods:

• readfile - read a file using the Node 'fs' (fileSystem) module
• writefile - write a file using the Node 'fs' module
• fileInfo - get information about a file using the Node 'fs' module
• specialN - perform some trivial arithmetic

Here is how this API is defined in the Definition pane of the Create Node API dialog:

The code is reproduced below:

define class fileoperations
    function readfile as c(filename as c)
        helptext "read file"
    end function
    function writefile as l(filename as c ,contents as c)
        helptext "write a file"
    end function
    function fileInfo as fileInfo(filename as c)
        helptext "return information about a file"
    end function
    function specialN as n(n1 as n ,n2 as n)
        helptext "does some math"
    end function
end class

define class fileInfo
    dim filename as c
    dim filesize as n
    dim fileTime as c
end class

Notice that the fileInfo method's return type is fileInfo. fileInfo is defined as a class that has these properties: filename, filesize and fileTime.

When you create Xbasic functions that return multiple values, it is common to define the return type of the function as P ( as pointer). In the case of a Node API definition, you cannot define a method whose return type is P. If you want to define a method that returns multiple values, you must define a class, as shown above, and set the function return type to the class.

The definition shown above simply defines what the methods of the Node API are and what input parameters each method takes. The Definition does not contain any Xbasic code to implement the functionality of each method.

The implementation for the above definition is shown below:

Note that the implementation is written using Node code.

exports.api = {
    //read file
    // inputs:
        // call.arguments.filename - string
    // returns: string
    readfile : function(call) {
        var fs = require('fs');
        var _cb = function(err,data) {
            if(err) {
                call.error(err);
            } else {
                call.return(data)
            }
        }
        fs.readFile(call.arguments.filename,'utf8',_cb);
    },
 

    //write a file
    // inputs:
        // call.arguments.filename - string
        // call.arguments.contents - string
    // returns: bool
    writefile : function(call) {
        var fs = require('fs');
        var _cb = function(err) {
            if(err) {
                call.return(false)
            } else {
                call.return(true)
            }
        }
        fs.writeFile(call.arguments.filename, call.arguments.contents,_cb);
    },

   
    //return information about a file
    // inputs:
        // call.arguments.filename - string
    // returns: fileInfo { filename : "" , filesize : 1 , fileTime : "" }
    fileInfo : function(call) {
            var fs = require('fs');
            var _cb = function(err,stats) {
            if(err) {
                call.error('file not found');
            } else {
                var _d = {filesize: stats['size'], 'fileTime' : stats['mtime'], filename: call.arguments.filename}
                call.return( _d );
            }
    }
    fs.stat(call.arguments.filename,_cb);
},
 

    //does some math
    // inputs:
        // call.arguments.n1 - number
        // call.arguments.n2 - number
    // returns: number
        specialN : function(call) {
            var n = call.arguments.n1 + call.arguments.n2
            call.return(n);
        }
};

The implementation is a Javascript file that exports an object with the same name as the Node API. This object has function for each of the methods in the API definition.

The prototype for the object is automatically created from the Node API definition.

Notice that the implementation of the fileInfo method returns an object with properties that match the definition of the properties of the fileInfo class in the Node API definition.

Each method defined in the Implementation takes as its input an argument called call. This argument is an object that has a property called arguments which contains the input parameters to the method and it also has two methods, return() and error(), that allow you to return a result from the function, or report an error.

To use this API from your Xbasic code:

'Dim an instance of the API class

dim fo as ::NodeServices::fileoperations

dim p as p
p = fo.fileInfo("c:\myfiles\file1.txt")
?p.filename
= "c:\myfiles\file1.txt"
?p.filesize
= 2942097
?p.fileTime
= "2017-05-10T14:26:04.193Z"

 

Xbasic - pdf_fillinFields_get() - Gets a list of the fill-in fields in a PDF file. If a PDF file is created with fill-infields, this function will extract the names of all of the fill-in fields in the file. You can optionally extract additional information about each field.

Syntax

c result = pdf_fillinFields_get(c pdfFilename [, L flagExtendedInfo])

IMPORTANT: This function wraps a 3rd party library which you must install yourself before you can use this function. The download link for this library is: https://www.pdflabs.com/tools/pdftk-the-pdf-toolkit/pdftk_server-2.02-win-setup.exe

Examples (from Interactive window):

dim fn as c

fn = "c:\mypdffiles\pdfform1.pdf

?pdf_fillinFields_get(fn)

= {
    "first_name": "",
    "last_name": "",
    "date": "",
    "football": "",
    "baseball": "",
    "basketball": ""
}

Get extended information (from Interactive window):

dim fn as c

fn = "c:\mypdffiles\pdfform1.pdf

?pdf_fillinFields_get(fn,.t.)

= [
    {"title": "first_name","fieldType": "Text","fieldFlags": "0","fieldValue": ""},
    {"title": "last_name","fieldType": "Text","fieldFlags": "0","fieldValue": ""},
    {"title": "date","fieldType": "Text","fieldFlags": "0","fieldValue": ""},
    {"title": "football","fieldType": "Button","fieldFlags": "0","fieldValue": ""},
    {"title": "baseball","fieldType": "Button","fieldFlags": "0","fieldValue": ""},
    {"title": "basketball","fieldType": "Button","fieldFlags": "0","fieldValue": ""}
]

Xbasic - pdf_fillinFields_merge() - Merges data into a PDF file that has fill-in fields, creating a new PDF file with the filled in data. You can use the pdf_fillinFields_get() function to get the name of the fill-in fields in the PDF file.

Syntax

L result = pdf_fillinFields_merge(c pdfFileIn, c pdfFileOut, c JSONData)

IMPORTANT: This function wraps a 3rd party library which you must install yourself before you can use this function. The download link for this library is: https://www.pdflabs.com/tools/pdftk-the-pdf-toolkit/pdftk_server-2.02-win-setup.exe

The field values that you use in the JSON data must match the defined 'Export value' in the PDF form. Win the PDF form designer, you can specify an 'export value' for each field. In the Example shown below, the 'Export value' for the 'football', 'baseball' and 'basketball' fields was defined as 'Yes'.

Example:

dim jsonData as c
jsonData = <<%str%
{
    "first_name": "Fred",
    "last_name": "Smith",
    "date": "12/18/2003",
    "football": "Yes",
    "baseball": "Yes",
    "basketball": "Off"

}
%str%
 

dim pdfIn as c

dim pdfOut as c

pdfIn = "c:\mypdffiles\pdfform1.pdf

pdfOut = "c:\mypdffiles\pdfform1_filled.pdf

pdf_fillinFields_merge(pdfIn,pdfOut,jsonData)

Xbasic - Functions - Arguments as Arrays - You can now specify that an input argument is an array by adding a suffix of [] to the argument name. Previously you had to set the input type of the argument to P if the argument was an array.

NOTE: The array is passed to the function by reference.

Example:

function asText as c(arr as c[])
    asText = crlf_to_comma( arr.dump() )
end function

Testing:

dim arr[2] as c

arr[1] = "alpha"

arr[2] = "beta"

?asText(arr)
= "alpha,beta"
 

Xbasic - Functions - Return Arrays - Previously, an Xbasic function could return an array by setting the return type of the function to a Pointer. Now you can explicitly set the return type to an array by adding a suffix of [] to the return type.

function asAnArray as c[] (commaList as c)
    commaList = comma_to_crlf(commaList)
    asAnArray.resize(line_count(commaList))
    asAnArray.initialize(commaList)
end function

Testing:

arr = asAnArray("one,two,three")
?arr.size()
= 3

?arr.dump()

= one
two
three

 

Xbasic - Functions - Return a typed Array - You can now define Xbasic functions that return arrays of an explicit type by adding a suffix of [] to the return type. Previously you could only return a generic Pointer value.

For example, assume you had defined the following class:

define class mynamespace::point
dim x as n
dim y as n
end class
 

You can now define a function that returns an array of the mynamespace::point type.

function ToPointArray as mynamespace::point[](points as c)
    points = strtran(points,";",crlf())
    ToPointArray.initialize_properties("x,y",points)
end function

 

Testing:

pa = ToPointArray("1,1;2,2;1,2")

? pa[1]
= x = 1
y = 1

Web Control Panel - UX Components - Pre-rendered Components - Warning Dialog -  If you update to a newer version of Alpha Anywhere and you open a web project that contains any UX components that have been set to pre-render and any of these components were last pre-rendered with an older version of Alpha Aynwhere, you will now get a warning telling you that these UX components need to be re-rendered. The warning dialog will allow you to click a 'Bulk Update' button to automatically update all of the UX components that need updating.

UX Component - List Controls - Offline Applications - PhoneGap - Using the File System to Persist List data - When you build a mobile app that is intended to operate offline, the typical pattern is to use List controls with Detail Views and to turn on the option to persist the List data to storage.

The data in the List are persisted to the browser's localStorage, which is limited to about 5mb of data.

Now, if your mobile application is run as a PhoneGap application, you can persist the List data to files in the device's file system. This will allow you to work with much more data while you are offline.

To turn on the feature to persist List data to the file system, set the Persist where property to FileSystem.

When you set the Persist where option to FileSystem, the Persist mode option is automatically set to Edits and the property is hidden.

If you set Persist where to LocalStorage, you can set the Persist mode to either 'Full', or 'Edits'.

In 'Full' mode, each time the data in the List are edited, the entire List is persisted to localStorage (this is the mode that is implicitly used in all versions of Alpha Anywhere prior to this version).

In 'Edits' mode, each time the data in the List are edited, only the edited rows are persisted to storage.

NOTE: f you select the FileSystem option and your component is not running in PhoneGap, Alpha Anywhere will automatically set the option back to LocalStorage.

How Persisting Data to the FileSystem Works

When you persist List data to localStorage, when the List is initially populated the List data is persisted to localStorage. Each time the List data are edited, the entire List is persisted again to localStorage (unless you change the Persist mode option to Edits).  Because writing to localStorage is so fast, and because there is a built-in limit (of approximately 5mb) to the amount of data that must be written to localStorage on each edit, there is no perceptible delay when you are editing the data in the List.

However, writing to the FileSystem is much slower than writing to localStorage and because there is no longer a built-in limit as to the amount of data in the List, a different approach is taken when the FileSystem option is used. When the List is initially populated, all of the data in the List are written to a file in the FileSystem. Each time the List is edited, the only the rows in the List that have been edited are written to a second file in the  FileSystem. This will file will typically be substantially smaller than the first file (that contains all of the List data), and since the file is likely very small, writing this file to the FileSystem will be very fast, and again, there will be no perceptible delay when you are editing data in the List.

When the List is synchronized data in the synced rows are written to a third file in the FileSystem and the primary keys of any deleted rows are written to a fourth file in the FileSystem.

The filenames of these four files in the FileSystem are:

• <namespace>.LIST.<listName> - the file that contains all of the List data. This file is only written to when the List is initially populated or refreshed. This file can be quite large (several megabytes) - much larger than would be allowed in localStorage. 
• <namespace>.LISTEDITS.<listName> - the file that contains the rows in the List that have been edited, but not yet synced. This file is updated each time the user makes an edit to the List data. This file is typically quite small.
• <namespace>.LISTSYNCEDEDITS.<listName> - the file that contains the rows in the List that have been edited and synced. This file is updated after the user had synced the List data. This file is typically quite small.
• <namespace>.LISTSYNCEDDELETES.<listName> - the file that contains the primary keys of the rows in the List that have been deleted. This file is updated after the user had synced the List data. This file is typically quite small.

Where:

<listName> - is the Id of the List.

<namespace> is the value of the Namespace property (see image below).

NOTE: If the List data are being persisted to localStorage, the Namespace property is used in constructing the localStorage key name. If the List data are being persisted to the FileSystem , the Namespace property is used in constructing the filenames for the four files used to persist the List data and edits.

Location of the List Data Files in the FileSystem

The files for the List data are stored in the device's 'saved' filesystem. The location of the device's 'saved' filesystem is returned by the {dialog.object}.phoneGapGetLocalDirURL('saved') method. The files are stored in a directory (called _offline by default) in this location.

The following methods can be use to get the file system URL and folder for the List data files:

{dialog.object}._persistFS() - the file system URL of the directory in which the List data sub-directory is located

{dialog.object}._persistFolder() - the sub-folder in which the files are actually stored - name has a trailing / character.

The actual folder name of the files is therefore:

{dialog.object}._persistFS() + {dialog.object}._persistFolder()

For example, the fully qualified name of the file that contains all of the data in the List when the list is initially populated is therefore (assuming the List id is LIST1 and the UX Local Storage Namespace property was set to NS1):

{dialog.object}._persistFS() + {dialog.object}._persistFolder() + 'NS1.LIST.LIST1'

NOTE: In the case where the component is running in AlphaLaunch, the base folder for the files is in a special folder returned by the  A5.shell.getAppFileStorageDir() method. The {dialog.object}._persistFS() will return the appropriate base folder name when the component is running in AlphaLaunch.

List Virtualization

If you are populating a List with a large amount of data, it is strongly recommended that you turn on the List's virtualization feature. With virtualization turned on, populating a List with a large amount of data is substantially faster than populating the List with virtualization turned off.

To turn on List virtualization, set the Virtualization type property to Dynamic as shown in the image below.

DetailView Button Genie

The DetailView Button Genie now has two new options as shown in the image below:

Delete List Storage - This deletes the files used to store the List data. (If the List is set to persist to Local Storage and the Persist mode is set to Edits, this option will delete the List data from localStorage)

Dump storage data - Dumps out the contents of the files that contain the List data (If the List is set to persist to Local Storage and the Persist mode is set to Edits, this option will dump the List data stored in localStorage). The data can be dumped to a file on the server, a bucket on Amazon S3, and can also be written to a DIV or placeholder on the screen.

NOTE The DetailView Button Genie is accessed by clicking the [List-Detail View-Buttons] item in the UX toolbox  Defined Controls section

.

Deleting Storage

You can delete the files that contain the List data using this Javascript:

var ls = {dialog.object}._localStorageSettings;
{dialog.object}._persistToLocalStorageInitializeKeys(ls,'listId',true);

Deleting the files that contain the List data can be useful when debugging an application.

Grid Components - Publish Meta Data Files - Published grid components do not include meta data that is needed to open the component in the Grid Builder. Therefore the published grid files found in the server webroot can not be edited in the Grid component Builder. A new option has been added to the publish profiles to 'Publish Grid Meta Data Files'. This option is selected by default and a special data file with the component name and a '_a5wcmp_metadata' file extension will be published when the grid is published.

NOTE: The motivation behind publishing meta data files is so that if a developer no longer has access to the original grid component files (.a5wcmp files) from the Web Project Folder, but does have access to the published .a5wcmp files, they will still be able to edit the Grid component files in the Grid builder (as long as they also have access to the published meta data files - _a5wcmp_metadata). The published files for all other component types (i.e. other than Grids) can be edited in the development program component builders (and therefore it is not necessary to publish meta data files for these component types).

The special _a5wcmp_metadata file is not used by the web server, but can be converted into the original editable grid using an option 'Create Grid Component From Meta Data File' found in the Web Control Panel 'More...' drop down.

This option should only be turned off if there are backup copies of the original grids available outside of the development system.

UX Component - Mobile Applications - Persistent Logins - A common pattern in mobile applications is to not require the user to login to the application after they have successfully logged in for the first time.  The login should be persistent until is is explicitly revoked by the action of an Administrator, or until the end of the persistent login period is reached.

NOTE: The canAjaxCallback server-side event previously would only emit user-defined Javascript if the event denied permission for the callback. Now, user defined Javascript can be emitted even if the Ajax callback is allowed. This change was made to support the Mobile Application with Persistent Login pattern.

For more information on the approach used to implement this pattern, please view this document.

Watch Video - Part 1
Watch Video - Part 2
Watch Video - Part 3
Watch Video - Part 4
Watch Video - Part 5
Watch Video - Part 6

Download Component
 

When you create a new UX component a new template is available for the persistent login pattern.

Alpha Anywhere Application Server - Self-signed Certificates - A change has been made in the way self-signed certificates are generated.

Alpha Anywhere Application Server - Request Object - As part of an ongoing initiative to standardize functionality between the Alpha Anywhere Application Server (AA Server)  and the Application Server for IIS (AA Server for IIS), the Request object in the AA Server server will be undergoing a number of changes. While no immediate action is required from developers, there are a number of planned changes that will potentially introduce incompatibilities for existing Xbasic code. Alpha Software is committed to minimizing the impact of these changes, and this release of Alpha Anywhere includes several new properties and methods on the Request object to allow developers to begin transitioning their code at their convenience. Future releases will continue to add functionality to ease this transition. All new functionality will work identically when running under either the AA Server or the AA Server for IIS.

The goal of these changes is to ensure that your applications will work identically on both the AA Server and the AA Server for IIS, thus allowing for a seamless transition between servers should you decide to deploy your app using the AA Server for IIS

New Functionality
 

• Request.A5WIncludePath  - a read-only character property indicating the path that will be used as the default location for a5w_inlude()
• Request.HttpMethod -  a read-only character property indicating the HTTP method used when the request was made. This is a replacement for Request.Request_Method, which is now deprecated.
• Request.GetCookie(CookieName as c) as System::Web::HttpCookie
• Request.HasCookie(CookieName as c) as l

Request.Cookies will be changing to be a System::Web::HttpCookieCollection in the future. Currently it is an Xbasic property class ("dot variable"). Once changed, any Xbasic code expecting a property class will fail. To prepare for the upcoming change, the new HasCookie() and GetCookie() methods can be used to replace code that directly operates on Request.Cookies. These methods will continue to work even after the underlying type of Request.Cookies is changed. These methods also work consistently in both the AA Server and the AA Server for IIS.

Request.GetCookie() returns null if the specified cookie does not exist, or returns a System::Web::HttpCookie instance if the cookie exists. Existence of the cookie can be checked in advance with Request.HasCookie().

Sample to see if a cookie exists:

if Request.HasCookie("MyCookie") then
    'cookie exists in the request
else
    'cookie is NOT included in the request
end if

Sample to read a cookie's value:

dim GreetingName as c = ""
if Request.HasCookie("Greeting") then
    dim GreetingCookie as System::Web::HttpCookie = Request.GetCookie("Greeting")
    GreetingName = GreetingCookie.Value
else
    GreetingName = "new user"
end if
Response.Write("Welcome " + GreetingName)
 

Sample of updating legacy code:
Sample old syntax:

dim MyCookieValue as c = ""
if eval_valid("Request.Cookies.MyCookie")
    MyCookieValue = Request.Cookies.MyCookie
end if
 

Sample new syntax:

dim MyCookieValue as c = ""
if Request.HasCookie("MyCookie")
    MyCookieValue = Request.GetCookie("MyCookie").Value
end if

• Request.GetHeader(HeaderName as c) - returns a header value as a string
   

Headers will be changing to a System::Collections::Specialized::NameValueCollection. Currently it is a character string containing the raw header text of the HTTP request. To prepare for the upcoming change, the new GetHeader() method can be used to replace code that directly operates on Request.Headers. These method will continue to work even after the underlying type of Request.Headers is changed. This method also works consistently in both the AA Server and the AA Server for IIS.

The Request.GetHeader() method always returns a string value. If the specified header name does not exist in the request, the returned value will be an empty string. There is no distinction between a header that does not exist, and a header that exists with an empty value.

Sample old syntax to get the value of a specific header:

dim HeaderValue as c = ""
HeaderValue = alltrim(extract_string(wr.Headers,"MyHeader: ",chr(10)))
 

Sample new syntax to get the value of a specific header:

dim HeaderValue as c = Request.GetHeader("MyHeader")

Deprecated Properties

• Accept - replace with GetHeader("Accept")
• AcceptCharset - replace with GetHeader("Accept-Charset")
• AcceptEncoding - replace with GetHeader("Accept-Encoding")
• AcceptLanguage - replace with GetHeader("Accept-Language")
• Cookie - replace with GetHeader("Cookie")
• HTTP_Request - no replacement
• IfModifiedSince - replace with GetHeader("If-Modified-Since")
• IfUnmodifiedSince - replace with GetHeader("If-Unmodified-Since")
• REQUEST_METHOD - replace with HttpMethod

Additional Documentation

Full documentation for the .Net class System::Web::HttpCookie can be found at https://msdn.microsoft.com/en-us/library/system.web.httpcookie.aspx

Full documentation for the .Net class System::Web::HttpCookieCollection can be found at https://msdn.microsoft.com/en-us/library/system.web.httpcookiecollection.aspx

Full documentation for the .Net class System::Collections::Specialized::NameValueCollection can be found at https://msdn.microsoft.com/en-us/library/system.collections.specialized.namevaluecollection.aspx

AlphaLaunch - Install Mobile Apps to Apple and Android Devices - AlphaLaunch is a free AppStore app that you can install on an Android or Apple device. Once AlphaLaunch has been installed on a device you can install as many Apps as you want to that device without having to go through the Apple or Android App stores, or without having to go through a PhoneGap build process (either Adobe PhoneGap Build or the Command Line Interface). The Apps are installed into AlphaLaunch, not directly to the device. This makes it extremely easy and quick to install new Apps on a device.

Watch Video - Part 1
Watch Video - Part 2
Watch Video - Part 3
Watch Video - Part 4

NOTE: AlphaLaunch is not licensed for use in a production environment if you do not have a subscription to the Enterprise Edition of Alpha Anywhere.

The use cases for AlphaLaunch include:

• You are developing a mobile App for a client and you want the client to be able to install and test the App on their own device
• Organizations that need to create many 'employee-facing' applications and need a quick way to deploy these applications to their user community
• You want a quick and easy way to update previously installed Apps on a device without having to wait for App store approval.

Once an App has been installed into AlphaLaunch it operates largely identically to the way in which it would operate had it been installed directly on the device. For example, even when there is no internet connection, you will be able to start any App that is installed in AlphaLaunch.

AlphaLaunch is not suitable as a means of deploying a public facing App that will be installed by many users who will go to the App Store to find and install your App. When an App is installed directly onto a device the App icon will appear on the device's home screen. However, when you publish to AlphaLaunch, the App will not have an icon on the home screen. To launch the App you will first have to launch AlphaLaunch and then you will be able to select the App from the list of Apps installed in AlphaLaunch.

NOTE: Apps installed in AlphaLaunch are PhoneGap applications (even though you did not have to go through the PhoneGap build process) and they can use any of the PhoneGap plugins that AlphaLaunch exposes. For more information see the section Understanding AlphaLaunch Limitations below.

NOTE: On Apple devices, there are other ways that you can allow a user to test an App that you are developing using the Apple Test Flight system. However, setting up Test Flight is complex. Alternatively, you could get the UDID of a user's device and use a special Apple publishing profile with PhoneGap build that allows Apps that you build to be installed on that user's device  (without having to submit the App to the App store). However, this too, is complex and you are limited to only 100 devices.

Understanding AlphaLaunch Limitations

• AlphaLaunch is branded as an Alpha Software App. If you want a version of the AlphaLaunch App that is branded with your company's logo and colors, please contact your Alpha Software sales person.
• The Apps that run in AlphaLaunch are PhoneGap Apps, but they can only use the plugins that AlphaLaunch was configured to use. If you want a version of AlphaLaunch that uses a different set of PhoneGap plugins, please contact your Alpha Software sales person.

To see the list of plugins that AlphaLaunch enables, tap the Settings button in the footer of the AlphaLaunch home screen.

Then make sure that the Show Support Settings switch is on.

Then scroll the screen till you see this menu item:

How to Install AlphaLaunch on a Device

To install AlphaLaunch on a device, simply go to the App Store and search for 'Alpha Launch'.

How to Run an App That Has Been Installed in AlphaLaunch

To run an App that was previously installed in AlphaLaunch, simply launch the AlphaLaunch App on your device by clicking the Launch icon.

Then scroll the list of installed Apps until you find the App that you want and tap on the App name.

How to Install An App Into AlphaLaunch

To install a new App into AlphaLaunch, tap the Manage/Add button in the footer of the AlphaLaunch App.

If there are any existing installed Apps a screen showing these apps will be shown.

Note that for each installed App, the name of the server from which the App was installed is shown. When an App is run, all Ajax callbacks are made to the same server from which it was originally installed.

'

You can use this screen to reorder the installed Apps. You can also use a 'press-hold' gesture on any of the Apps in the List to bring up a screen that will allow you to uninstall an App or to update the App.

Tap the Add button to  bring up a list of the available Apps on the server that AlphaLaunch is currently configured to use.

For each App that is listed, there is either an Install or Reinstall button. The Install button will appear if the App is not currently installed and the Reinstall button will appear if the App has previously been installed. Reinstalling a previously installed App is effectively updating the App to a newer version of the App.

How to Select the Active AlphaLaunch Server

When you click the Add button on the Manage App List screen, the Apps that are available on the active AlphaLaunch server are shown. You can change the active AlphaLaunch server by tapping the Settings button at the AlphaLaunch home screen.

Then, tap on 'Server Web Address for Downloading Apps....

This will bring up the list of registered servers.

Tap on the server you want to select, then tap the Select button.

NOTE: The Active AlphaLaunch server only controls the list of available Apps that you can install when you press the Add button to install a new App. If an App (called 'App1' for example) was installed from 'Server1' and then the active server is changed to 'Server2', when App1 is running, it will make Ajax callbacks to 'Server1', regardless of what server is currently designated as the 'active' server.

How to Register a New AlphaLaunch Server

To register a new AlphaLaunch server, follow the instructions (above) for selecting the Active AlphaLaunch server. On the Server List screen (shown above), tap the Add button.

This will bring up the Edit Server Info screen where you can either type in the server address or scan a special QR code that encodes all of the necessary information.

How To Publish an App to AlphaLaunch

To publish Apps to AlphaLaunch open the Web Control Panel and select the project that contains the Apps that you want to publish.

NOTE: An 'App' is a UX component. The UX component can call child UX components, but these child UX components should typically be configured as Precomputed so that they can load directly from the device (so as not to be dependent on an Internet connection).

Before you publish Apps to AlphaLaunch you must first 'register' the Apps you want to publish. Registering an App involves defining how the App will appear when it is shown in the AlphaLaunch home screen and how it will be described when a user displays the list of available Apps that can be installed into Alpha Launch

Registering Apps To Be Published to AlphaLaunch

To register the Apps from a particular Web Project for publication to AlphaLaunch, tap the More... button on the extreme right of the Web Control Panel.

Then select the AlphaLaunch, Publish Apps to AlphaLaunch... menu item.

This will bring up the AlphaLaunch dialog where you can register the Apps from the Web Project that you want to publish to AlphaLaunch.

To register a new UX component, click the Add component button and then select the UX component you want to publish.

The AlphaLaunch dialog will then show the component that you selected and the orange icon will indicate that the settings for this component have not yet been defined.

Either double click on the component name, or click the Edit component settings button to open the AlphaLaunch Settings dialog box.

The important properties on this dialog include:

• ID - the ID must be unique across all App that are installed in AlphaLaunch. It is common to use a reverse URL format for the ID (e.g. com.mydomain.myappname), but this is not required. The ID will be used in future versions of AlphaLaunch to allow one AlphaLaunch App to communicate with another AlphaLaunch App.
• Name - the name of the App. This is the name that is shown on the AlphaLaunch home screen and in the list of available Apps that can be installed into AlphaLaunch when a user adds a new App to AlphaLaunch.
• Description - the App description. This is the description that is shown on the AlphaLaunch home screen and in the list of available Apps that can be installed into AlphaLaunch when a user adds a new App to AlphaLaunch.
• Version - this is the App version.
• Minimum size - this defines the minimum screen resolution of the device that the App can be installed on. You can leave this blank if you do not wish to set a minimum size.
• Maximum size - this defines the maximum screen resolution of the device that the App can be installed on. You can leave this blank if you do not wish to set a maximum size.
• Template - The template defines how an installed App will appear on the AlphaLaunch home screen. By checking the Advanced mode property, you  have complete control over the template. The template can include special placeholders (e.g. {name} and {desc} ) to show the App name and description. If you want to use a default template style, do not check the Advanced mode property. You will then be able to select the App icon and background color of the row for this App in the list of installed Apps.
• Icon type - You can either use an SVG or bitmap as the icon for the App. The icon is shown in the list of installed Apps at the AlphaLaunch home screen.
• Download location - If you leave this property blank, the App files are download from a folder in the webroot of your Alpha Anywhere server. However, you can download the App files from another server if you wish. For example, you might want to have AlphaLaunch download the App files from Amazon S3. In this case you would enter the URL of the bucket on S3 where you have placed the App files. For example: http://mys3account.s3.amazonaws.com/app1. For more information on why you might want to specify another server (such as S3) as the download location see App Install Errors below.

You can preview how the App will appear in the AlphaLaunch home screen by clicking on the Preview app template hyperlink at the bottom of the screen.  For example, here is a preview of a template that is using a purple background color and an SVG icon.

Once you have registered all of the Apps in a Web Project that you want to publish to AlphaLaunch you are now almost ready to publish to AlphaLaunch.

But before you can publish you must first define a Publishing Profile that indicates where the Apps will be published (i.e. the Alpha Anywhere server and folder on that server where the Apps will be published). To define a publishing profile, click the Profiles button on the toolbar when the Web Project Control Panel has focus.

NOTE Each Web Project will typically be published to its own AlphaLaunch server address. For example, you may have 3 UX components in 'Web Project1' that you want to publish to AlphaLaunch and (say) 2 UX components in 'Web Project2' that you want to publish to AlphaLaunch. In both cases you may want to use the same physical Alpha Anywhere server. The Publishing Profile that you define for 'Web Project1' might specify that you want to publish to a folder called 'webProject1', in which case the server address for the 3 Apps in this group of Apps might be something like 'http://www.myAAserver/webProject1'. On the other hand, the Publishing Profile you define for 'Web Project2' might specify that you want to publish to a folder called 'webProject2', in which case the server address for the 2 Apps in this group of Apps might be something like 'http://www.myAAserver/webProject2'.

Once you have defined the publishing profile, click the Publish Apps to AlphaLaunch Server button on the AlphaLaunch dialog.

This will bring up the Publish to AlphaLaunch dialog. You will need to select the Publishing Profile to use and you will also need to specify the Sever URL (i.e. the url of the location where the Apps are being published).

Once you have published your Apps you will need to register the server in AlphaLaunch. AlphaLaunch will contact the server to get a list of the available Apps.

For instructions on how to register a server with AlphaLaunch, see the section above titled How to Register a New AlphaLaunch Server . To make it easy to register a new AlphaLaunch server (i.e. to avoid having to type in a long server URL on a mobile device keyboard), you will probably want to generate a QR code with with server address. Check the 'Show a QR code...' property before you click the OK button.

You can use Advanced mode when you want to republish to AlphaLaunch after having made a change to the App settings (e.g. the App template, description, version number, etc.), but not the App itself. This will speed up the process of publishing the Apps because it will avoid having to recreate the static fileset for each App.

Adding an Exit Button to your App

When an App is run in AlphaLaunch you will typically want to add an 'Exit' button to your App to go back to the AlphaLaunch home screen. If you do not add an Exit button, then after the user launches the App they will not be able to get back to the AlphaLaunch home screen to launch a different App.

You can use Action Javascript to add an Exit button, or you can code the Javascript for the button yourself.

To use Action Javascript, select the 'AlphaLaunch Actions' action for the list of available Action Javascript actions.

To code the Javascript directly, use this code:

if(A5.shell) {A5.shell.exitComponent();};

The code tests if you are running in AlphaLaunch, then if you are then it calls the A5.shell.exitComponent() method.

Troubleshooting

The most common problem with AlphaLaunch is that after you have published Apps to your AlphaLaunch server and you then go to AlphaLaunch to install the Apps you just published, the Apps are not listed on the Apps to Install screen. This cause of this problem is either the Application Server has not been started, or the Server Addrtess (i.e. URL) that was entered in the Publish to AlphaLaunch dialog was incorrect.

You can test if you entered a valid server address by going to a browser and entering the following URL into the browser

<server URL>/availableAppInfo.txt

 For example, if your server URL was entered as:

http://192.168.70.157/AlphaLaunchDemo

You would enter this address into the browser address bar:

http://192.168.70.157/AlphaLaunchDemo/availableAppInfo.txt

If you do not receive a response, then it is likely that the server URL that you specified is incorrect.

App Install Errors

If you are installing an App from a folder on an Alpha Anywhere standard server (as opposed to the Alpha Anywhere Server for IIS), you might get an install error if the App has a large number of files. This is because the Alpha Anywhere server limits the number of files that can be simultaneously served. The error will not occur if you are using the Alpha Anywhere server for IIS. You can work around this problem by copying the folder that contains your App files to a bucket on Amazon S3 and then setting the Download location for the App to the URL of this S3 bucket.

AlphaLaunch Methods

A5.shell.exitComponent() -- Exit the App that is running an return to the AlphaLaunch home screen

A5.shell.getAppDir() - Returns the file URL of the local directory with the App's files

A5.shell.getAppFileStorageDir() - Returns the file URL of the local directory where the Apps data files are stored (this is separate from other Apps).

UX and Grid Component - Language Definitions - High Order Characters - When you tag strings in a Grid or a UX with language tags (<a5:r> ...</a5:r> you must then define how the tags are resolved in each of the different supported languages. Previously when entering high order characters, it was necessary to HTML encode the character. Now you can just type in the characters directly into the Language Definition dialog box.

UX Components - Pre-render - Working Preview - Internet Explorer - jQuery - When you do a Working Preview of a UX component and all of the following conditions are met:

• The UX is set to pre-render
• Working Preview is set to use Internet Explorer, not Chrome
• jQuery is set to load using the Internal version (set in the Project Properties dialog)

then jQuery will not be loaded.

If you need to have jQuery loaded while you are in Working Preview then you can either switch to Chrome for Working Preview, or change where jQuery is loaded from.

If you cannot switch to Chrome for Working Preview, and you cannot change the location from which jQuery is loaded, then you will have to make an Ajax callback to load jQuery. For example, you could use the following Xbasic function to handle the Ajax callback that loads the internal version of jQuery.

function loadJQuery as c (e as p)
    loadJQuery  = __hidden__javascript__a5_jquery_core() + crlf() + __hidden__javascript__a5_jquery_ui()
end function
 

Xbasic Function Libraries, Modules and Classes - Encrypt - Password Protect - When you create Xbasic Function Libraries, Modules or Classes in your Web Project you can now specify that the files should be encrypted, or both encrypted and password protected.

In order to encrypt a file the first line of the file must be an Xbasic comment (with no leading spaces):

'ENCRYPT

In order to both encrypt and password protect a file the first line of the file must be an Xbasic comment (with no leading spaces) of this form:

'PASSWORD:your_password

For example:

'PASSWORD:mysecretpassword

At run-time encrypted files are automatically decrypted.

If a file is password protected, then when you try to edit the file from the Web Control Panel, you will be prompted to enter the password. Once you have successfully supplied the file password you will no longer be challenged for the password when you next edit the file (until you exit from the Alpha Anywhere IDE).

.Net v4.6.2 - The Alpha Anywhere Installers now install .Net V4.6.2 if it has not previously been installed. Previously, the installers were installing v4.6.1

• an event is added
• an event is edited
• an event is moved
• an event is deleted

There are no built-in hooks for these events, but you can easily define you own.

For the event added, edited, or deleted cases, you can add event handlers as follows:

• Edit the UX component used to edit events and add the functions shown below to the Xbasic function declarations

function onEventDelete as v (e as p)
end function 
function onEventUpdate as v (e as p)
end function 
function onEventAdd as v (e as p)
end function

• Edit the UX component used to edit events and modify the server-side afterDialogValidate event to add calls to the onEventUpdate and onEventAdd functions. See below.
• Edit the UX component used to edit events and modify the deleteEventXbasic Xbasic function by adding the following at the end of the function: onEventDelete(e)

How to Update the afterDialogValidate Event Handler Function
Make the changes shown in red to the afterDialogValidate  event.

To handle the event is moved case, edit the Web2Cal component and add this code to the onComponentExecute server-side event:

if eval_valid("request.variables._XbasicFunction") then 
	if request.variables._XbasicFunction = "updateEvents" then 
		'event was moved -- event data is in request.variables._calEvent_eventId, etc.
	end if 
end if 

Features

Xbasic - a5_json_to_excel() Function - Export JSON Data to Excel - Exports data in a JSON document to an Excel file. If the JSON document is an object with multiple arrays, each array is exported as a separate sheet in the Excel file.

If the JSON document is an array, the Excel file will have a single sheet called 'Table1'

Syntax:

L flag = a5_json_to_excel(c Json, c filename)

Where

• flag = .t. or .f. - indicates if the Excel file was created
• json - the JSON data to export to Excel
• filename - the filename of the Excel file (must have a .xlsx extension)

For example, if the JSON document shown below was exported to Excel, the Excel file would have two sheets ('customers' and 'phoneNumbers'). Each sheet would have the data in the corresponding array in the JSON data.

			{
	"customers" : [
		{"id": "1", "firstname" : "Fred", "lastname": "Jones"},
		{"id": "2", "firstname" : "Mary", "lastname": "Nickerson"}
	],
	
	"phoneNumbers" : [
		{"id": "1", "type" : "Home", "number" : "555-555-1234"},
		{"id": "1", "type" : "Office", "number" : "555-555-1235"},
		{"id": "2", "type" : "Home", "number" : "555-555-1236"},
		{"id": "2", "type" : "Office", "number" : "555-555-1237"},
		{"id": "2", "type" : "Vacation", "number" : "555-555-1238"}
	]
}


			

TabbedUI - onLogin Server-side Event - This event can now set data values that will be available when the client-side afterLogin event fires.

For example, you could add this code in the server-side onLogin event:

e.eventDataObject = "{userName: '"+e.userName+"', var2: 'some other value', timeOfLogin: '"+js_escape("" + now())+"'}"
 

In the client-side afterLogin event you can refer to any value in the eventDataObject.

For example:

alert('Welcome: ' + e.eventDataObject.userName );
 

Reports - Free-form Reports - Vertical Lines - Growable - You can now set the Growable property on vertical lines in a report. When this property is set, the vertical line will grow to the full height of the report section it is in.

For example, in the report shown below, the vertical line extends the full height of each record in the Detail Section without any gaps between the lines.

Videos

Features

Alpha Anywhere Application Server - TLS Protocol - The Alpha Anywhere Application Server now allows the server administrator to specify the minimum TLS protocol version supported. While SSL v2 and SSL v3 had been fully removed from the Alpha Anywhere Application Server some time ago, it has not been possible to fully disable older TLS versions until now. This setting allows TLS 1.0 and TLS 1.1 to easily be completely turned off, if desired.

TLS 1.2 is the most recent protocol and generally considered to be the most secure. Setting the minimum TLS version to 1.2 will disable TLS 1.0 and TLS 1.1 and provide what is currently considered the highest level of security. Note however that not all older web browsers or operating systems support TLS 1.2. Site administrators should evaluate the needs of their users before modifying this setting.

This setting defaults to TLS 1.0, in order to prevent unexpected client connectivity issues.

Videos

Features

UX Component - Copy/Paste Controls - The UI for copying and pasting controls has been simplified.

Grid, UX and TabbedUI Builder - Collapse/Expand Property Grid Categories - You can now quickly collapse or expand all categories in the Property Sheets. This can make it easier to find a property without having to open the Properties search dialog.

PhoneGap App Builder - Icons and Splash Screens - The way in which icons and splash screens (iOS calls them launch images) has been completely rebuilt and a new option has been added to the Application Master Image Resources category that allows you to generate a series of 9-patch splash screen images for Android devices (iOS does not support 9-patch images without additional libraries).



 

VERY IMPORTANT: It is very important that you create a new PhoneGap Project when generating custom icons and splash screens for your app because the PhoneGap app config.xml file has been changed to support new functionality.

When you supply a single image that needs to be resized for the numerous aspect ratios required by all of the different types of mobile devices, the aspect ratio will typically change and the resulting image will be out of proportion. The new resizing code uses a center weighting technique to clip the image without any change to the image aspect ratio. This technique is used for the generation of all of the splash screens and you need to be aware of that when you supply the images for the portrait or landscape orientations.
 

Recommended Image Sizes
For portrait splash screens, the recommended size is 1536px x 2048px.
For landscape splash screens, tre recommended size is 2048px x 1536px.
You can also specify a square image (suggested size is 2732px x 2732px) for both orientations and the resulting images will not be distorted.

Android 9-patch images
A 9-patch image is a standard png file that has been divided into a matrix of 3 x 3 rectangles (like a tic-tac-toe board). Each region in the matrix has specific stretch properties that allow the image to be resized without altering the aspect ratio of the center weighted rectangles. As such, 9-patch images can be stretched to fit the different screen sizes without clipping or distortion. You need to supply a square image that will be used for both portrait and landscape modes and the graphics need to be center weighted. The recommended size is 2732px x 2732px.

For more info on 9-patch splash screen images see: Cordova Splashscreen Plugin Documentation

 

NOTE:  iOS Storyboard Launch Images -  If you open and inspect the new config.xml file you will see support for iOS storyboard launch images (which act much like Android's 9-patch images). While the support is included in the image builder module, it hasn't been exposed because the current version of PhoneGap Build does not support it. As soon as PhoneGap Build supports the inclusion of iOS storyboard images, we will expose iOS storyboard support within the PhoneGap App Builder.

PhoneGap App Builder - Use ImageMagick Option -  This option has been removed as all icons and splash screens are now generated using ImageMagick.

UX Component - List Control - deselectAll() Method - A new method has been added to the List control to un-select all selected rows in a List.

Contrast this method with the low level ._deselectAll() method which also un-selects any selected rows in a List, but does not perform any action on child Lists or the associated Detail View that the List may have..

The .deselectAll() method wraps the ._deselectAll() method, but in addition to un-selecting rows in the List, if the List has child Lists with pre-fetched data, the selected rows in all child Lists are also un-selected, and the Detail View for the List (and the Detail View for any child Lists with pre-fetched data) is disabled (if the 'No record in List selected' property for the top-most parent List is set to 'Disable Detail View').

For example:

var lObj = {dialog.object}.getControl('CUSTOMERLIST');

lObj.deselectAll();

UX Component - Data Series - Publish to Client-side - You can now specify that the data in Data Series should be published to the client-side so that it can be used in your Javascript code.

You define Date Series either by clicking on the smart field for the Data Series property (on the UX Builder Properties pane) , or by click on the Menu button.

Your Javascript code can reference the data in a Data Series using the following syntax:

{dialog.object}._dataSeriesData.SeriesName.SubSeriesName

If the Data Series has no sub-series, then syntax for referencing the Data Series is:

{dialog.object}._dataSeriesData.SeriesName

Understanding Data Series

A Data Series is a series of values. Say you have a SQL query that returns the data shown in the table below.

Each column in the table is a series of data. For example, the data series in the pink Firstname column is

Fred, John and Sally.

The name of the Data Series represented by the pink column in the above table is:

Names.Firstname

(where 'Names' is the arbitrary name given to the data table)

A common use case for Data Series is in charting applications. Both the Chart and Javascript Chart control in the UX component consume data series for the data shown in the charts.

Action Javascript

There is a new action in Action Javascript to perform actions on Data Series. The Data Series Actions action allows you to:

• Refresh DataSeries - refresh the data in one or more Data Series. The action is only meaningful if you specified that your Data Series data should be published to the client-side. An Ajax callback is made and the SQL query or custom Xbasic code that gets the data for the Data Series is executed. The new data is then published to the client-side
• Read DataSeries - gets the data in a Data Series and assigns it to a Javascript variable.

UX Component - Javascript Charts - A new option for generating charts in the UX component is now available. Javascript Charts generate charts using client-side data. Because Javascript Charts are generated using Javascript with client-side data, they are ideal for disconnected mobile applications.

 

NOTE: Javascript charts are based on the open source RGraph charting library. Only the SVG charts in this library are built into Alpha Anywhere. If you want to use any of the Canvas charts in this library, you can, but you will need to write the Javascript yourself.  For more information go to http://www.rgraph.net.

Contrasting Javascript Charts with the Chart Control

The Chart controls is a server-side control. The chart is rendered as a bitmap on the server and then the client-displays the bitmap image. Because the Chart control is a server-side control, it is not suited for disconnected applications. Also, since the Chart control is a server-side control, it will be slower than Javascript Charts.

To add a Javascript Chart to a UX component, select the [Javascript Chart] control in the Other controls section of the UX toolbox.

NOTE:  Tthe Chart control (i.e. the server-side charting control) is available in the Data Controls section of the UX toolbox.


 

After you add a Javascript Chart to your UX, you can then edit the Javascript Chart properties by clicking the smart field for the Chart properties property.

This will open the Javascript Chart builder, as shown below.

The top half of the screen is where you enter the Javascript code that generates the chart and the bottom half of the screen allows you to get a quick preview of the Chart.

In most cases you will get a quick start by selecting one of the Sample Charts. This will enter the Javascript for the selected chart and you can then tweak the Javascript to get the chart appearance that you want. You will likely also want to base the chart on real data, not the sample data shown in the sample chart.

To select a sample chart, click the Select Sample Chart button. This will open up a dialog showing the available sample charts:

Select the sample chart that you want. It will then fill in the Javascript for that chart into the builder. For example:

The Javascript shown in the window is the Javascript used by the RGraph charting library to render the Javascript chart.

Understanding the Pattern Used for the Chart Javascript

All of the sample charts insert Javascript that follows the same pattern.

var _settings = function() {

        //function that returns an RGraph settings object

}

var _chart = new RGraph.SVG.Bar(_settings()).draw()

{dialog.object}._jsCharts['{chartName}'] = {};
{dialog.object}._jsCharts['{chartName}'].settings = [_settings];
{dialog.object}._jsCharts['{chartName}'].object = [_chart];
 

Depending the RGraph chart type (e.g. Pie, Line, Bar, etc.), the appropriate RGraph function is called to render the chart.

A settings object is passed to the RGraph function. This settings object is created by calling the _settings() function.

NOTE: You do not need to include the RGraph charting Javascript libraries yourself in your UX component. The libraries are automatically loaded by Alpha Anywhere.

The Chart settings are stored in the _jsCharts object in the UX component object. These settings are stored to enable the chart to be refreshed with new data, to be changed on the fly by changing any of the chart properties, or to be dynamically resized. Notice that the settings object and the object object are arrays. This is because a chart can actually be composed of multiple charts each drawn on the same DIV.

The Javascript for the chart uses two special placeholders:

• {chartDiv} - The id of the div where the chart will be rendered.
• {chartName} - The name of the chart. This resolves to the Chart Id shown in the Javascript Chart property sheet.

Using Real Data in a Chart

When you select a Sample Chart, the Javascript that is inserted into the Javascript window in the Javascript Chart builder uses static data. This is fine initially when you are designing a chart, but at some point you will want to replace the static sample data with 'real' data.

The source of this 'real' data must be client-side data. For example, it might be data from a column in a List control. You will need to create a Javascript function that gets the data from the List and then set the data property in the Chart settings to the this function.

In many cases the 'real' data will be data that you want to get by querying a database, calling a service (REST, SOAP, etc.), or running some custom server-side code. In the case where the data you want to use in your chart originates on the server, you will need to define a Data Series that retrieves the necessary data. (When you define the Data Series you will need to specify that the Data Series data should be 'published' to the client-side.)

For example, here are the settings for a simple bar chart that uses static sample data:

var _settings = function() { 
   var settings = {
      id: '{chartDiv}',
      data: [8,5,9,3,5,2,4],
      options: {
          gutterTop: 50,
          hmargin: 20,
          xaxisLabels: ['Monday','Tuesday','Wednesday','Thursday','Friday','Saturday','Sunday'],
          tooltips: ['Monday','Tuesday','Wednesday','Thursday','Friday','Saturday','Sunday'],                
          title: 'A basic Bar chart',
          titleSubtitle: 'A chart showing daily values for a week',
          titleSubtitleItalic: true,                
          colors: ['#7e9cf6'],
          shadow: true,
          shadowOpacity: 0.2,
          attribution: false
       }
   };
   return settings;
}
var _chart = new RGraph.SVG.Bar(_settings()).draw();			

Notice that the chart data is defined by the data property in the settings object.

Say we have a Javascript function that returns an array of values and we want to use the data returned by this function in the Chart. For example, the function that return an array of values could be defined as follows:

function getData() {

    return [1,2,3,4,5,6,7];

}

To base the Javascript Chart on the data returned by this function, we simply change the data property in the Chart settings to:

....

id: '{chartDiv}',
data: getData(),
options: {....

In the case where the data comes from a column in a List control, the Javascript function that gets the data would be something like this (assuming that the column in the List that contains the data is called 'Sales'):

function getData() {

    var lObj = {dialog.object}.getControl('myList');

    var _d = lObj._data //get list data

    var _a = []; //make empty array

    for(var i = 0; i < _d.length; i++) {

        _a.push(_d[i].Sales); //push data from the 'Sales' column onto the array

    };

    return _a;

}

If the data you want to use in your chart originates server-side, then you will need to create a Data Series. Assume you have created a Data Series called Sales, with two sub-series, Amount and Month.

The data in the Sales Data Series might look something like this:

You can reference data from Amount column in the above Data Series using this syntax:

{dialog.object}._dataSeriesData.Sales.Amount

Using this syntax, you could change the settings object for the example bar chart to:

var _settings = function() { 
   var settings = {
      id: '{chartDiv}',
      data: {dialog.object}._dataSeriesData.Sales.Amount,
      options: {
          gutterTop: 50,
          hmargin: 20,
          xaxisLabels: {dialog.object}._dataSeriesData.Sales.Month,
          tooltips: {dialog.object}._dataSeriesData.Sales.Month,                
          title: 'A basic Bar chart',
          titleSubtitle: 'A chart showing sales by month',
          titleSubtitleItalic: true,                
          colors: ['#7e9cf6'],
          shadow: true,
          shadowOpacity: 0.2,
          attribution: false
       }
   };
   return settings;
}
var _chart = new RGraph.SVG.Bar(_settings()).draw();			

Notice that the chart data, X axis labels and tooltips are all based on Data Series data.

Any Property in the Chart Can Be Dynamic

In the above examples we have set the Chart's data property to the result of a Javascript function call (first example), or to the value in a Data Series (second example). However, it is not just the Chart's data property that can be dynamic. Any property in the Chart settings can be set to a Javascript function, or Data Series value.

For example, in the above example, the Chart Title is defined using this settings:

titleSubtitle: 'A chart showing sales by month'

This could be changed to:

titleSubtitle: getChartTitle()

Working in the Javascript Chart Builder

When you are working in the Javascript Chart builder, the dialog has these buttons and hyperlinks.

The purpose of each of these buttons or hyperlinks is:

• Select Sample Chart - opens a window showing sample charts. You can select a chart and the Javascript for the selected chart will be entered into the builder
• Preview Chart - Previews the chart in the bottom half of the window.
• Define Chart CSS - In some cases your Chart settings will use CSS classes for some aspect of the Chart (for example, formatting tooltips). You can define the CSS classes here.
• Color - Allows you to insert the value of a color into the Javascript code. If you highlight an existing color in the Javascript code before you click on the Color hyperlink, the highlighted color will be shown in the color picker. The color you select will be inserted into the Chart Javascript.
• Property name - The Javascript shown in the code window after you select a Sample Chart typically only sets a small number of the available properties for the Chart. If you click the hyperlink you get a list of some of the other available properties. Note: This list may include properties that are not appropriate for the type of chart you are designing. To read documentation about the available properties, please refer to the RGraph web site. (http://RGraph.net)
• Validate Javascript - the code you enter into the Code window in the Javascript Chart builder is Javascript. It must, of course, be valid Javascript. This hyperlink lets you validate the Javascript so you can check that you have not made any syntax errors when editing the sample code.
• Select Data Series - If you want to set the value of any property in the Chart Settings to data in a Data Series you can click this hyperlink to insert the Javascript to reference a Data Series. When you click the hyperlink, a window showing all of the available Data Series will be shown. You can define new Data Series in this window. When you select a Data Series (and sub-series if the selected Data Series has sub-series) the appropriate Javascript is entered into the code.

Setting a Chart's Background Color or Border

In some cases, you will want to set the background color or border of a chart. For example, the Chart shown below has a black background.

You can set the Chart background color and border using the Javascript Chart's Style property.

Setting Javascript Chart Size to 100%

You can set the Javascript Chart width to 100% (useful when the Chart is shown in a Panel Card). However, setting the Chart's height to 100% is not supported. You must specify an explicit height for the Chart. Also, unlike many other UX controls, Javascript Charts do not have a Fill Container property.

NOTE: If you set the Javascript Chart width to 100% and the Javascript Chart is contained inside a Panel Card, the Javascript Chart will automatically be resized when the device orientation is changed.

Action Javascript Javascript Chart Actions

The Javascript Chart Action in Action Javascript allows you to:

• Refresh Data in Chart(s) - Allows you to refresh the data in one or more Charts. If any of the selected Charts have any properties that are set to a Data Series, this action makes an Ajax callback to the server and refreshes the data in all of the referenced Data Series.
• Resize a Chart - Resizes a chart. You can specify a new height and width for the Chart using CSS syntax. e.g. '500px'. You can use percentages for the width property, but not the height property. When the Chart is redrawn at its new size, by default, it will use the same draw method that was defined in the Chart settings. For example if the Chart is set to use animation when it is rendered, the Chart's 'draw method' will be 'grow' (or one of the other animation methods supported by RGraph). You might want the Chart to render at its new size without using animation. You can override the default draw method and specify an explicit draw method. For example, if the Chart was defined to use the 'grow' method, you can specify 'draw' to redraw the Chart without using animation.
• Redraw a chart - Redraws a Chart. Like the Resize a Chart action, you can override the default 'draw method' when the Chart is redrawn. Typically used when one or more properties in the Chart settings are based on Javascript functions to re-render the Chart with new settings values returned by the Javascript functions.
• Set Chart Properties - Allows you to explicitly set any of the Chart's properties and then redraw the Chart. Like the Resize a Chart action, you can override the default 'draw method' when the Chart is redrawn after its properties have been set.

Methods

The following methods are available for working with Javascript charts:

{dialog.Object}.jsChartResize(UXJavascriptChart,width,height[,redrawMethod[,methodParameter]])  

Resizes a Javascript chart. You can optionally pass in a draw method to redraw the chart without animation, or with a specified animation option.

Where:

• UXJavascriptChart - name (i.e. Chart id) of the Javascript chart you want to resize.
• width - new width of the chart. Use CSS syntax. e.g. '500px'
• height - new height of the chart. Use CSS syntax. e.g. '500px'
• redrawMethod - you can override the default 'draw' method specified when the chart was defined. For example, if the chart was originally defined to use the 'grow' method (so that the chart is animated when it is drawn), you can override this and specify the 'draw' method (so that the chart is redrawn at its new size without animation.
• methodParameter - if you specify an explicit redrawMethod, if the method that is specified takes a parameter, you can use this argument to supply the parameter. For example, the 'grow' method can take this parameter: {frames: 100}

{dialog.Object}.jsChartSetProperties(UXJavascriptChart, properties [,drawMethod [,methodParameters]])

Resizes a Javascript chart. You can optionally pass in a draw method to redraw the chart without animation, or with a specified animation option.

Where:

• UXJavascriptChart - name of the Javascript Chart (i.e. Chart id)
• properties - an object with values for the properties you want to set. If the Chart is made up of multiple sub-charts, then you must pass in an array of property objects. For example, say that a Chart is comprised of a Bar Chart and a Pie Chart superimposed on the Bar Chart in the top left hand corner and you want to set the colors of the bars in the Bar Chart and the pie slices in the Pie Chart. Since the Chart is comprised of two sub-charts, you must pass in an array of properties. For example: [ {colors: ['blue']}, {colors: ['blue','red','green'}] .
• drawMethod - you can override the default 'draw' method specified when the chart was defined. For example, if the chart was originally defined to use the 'grow' method (so that the chart is animated when it is drawn), you can override this and specify the 'draw' method (so that the chart is redrawn at its new size without animation.
• methodParameter - if you specify an explicit redrawMethod, if the method that is specified takes a parameter, you can use this argument to supply the parameter. For example, the 'grow' method can take this parameter: {frames: 100}

{dialog.Object}.jsChartRefreshData(UXJavascriptChart)

Refreshes the data in Data Series that the Chart uses and then redraws the Chart.  An Ajax callback is made to the server to refresh the Data Series and then the Chart is redrawn using the new data. If the Chart is not based on any Data Series, then no Ajax callback is necessary and the Chart is redrawn.

Where:
 

• UXJavascriptChart - name of the Javascript Chart (i.e. Chart id). You can enter a comma delimited list of Chart names. If you specify multiple Charts, each of which is based on one or more Data Series, a single Ajax callback is made to refresh all of the Charts.

{dialog.Object}.jsChartRedraw(UXJavascriptChart [,drawMethod [,drawMethodParameters [,properties]]])

Redraws a Javascript chart. You can optionally pass in a draw method to redraw the chart without animation, or with a specified animation option. You can also
optionally change chart property values when it is redrawn.

Where:

• UXJavascriptChart - name of the Javascript Chart (i.e. Chart id)
• drawMethod - you can override the default 'draw' method specified when the chart was defined. For example, if the chart was originally defined to use the 'grow' method (so that the chart is animated when it is drawn), you can override this and specify the 'draw' method (so that the chart is redrawn at its new size without animation.
• drawMethodParameter - if you specify an explicit redrawMethod, if the method that is specified takes a parameter, you can use this argument to supply the parameter. For example, the 'grow' method can take this parameter: {frames: 100}
• properties - an object with values for the properties you want to set. If the Chart is made up of multiple sub-charts, then you must pass in an array of property objects. For example, say that a Chart is comprised of a Bar Chart and a Pie Chart superimposed on the Bar Chart in the top left hand corner and you want to set the colors of the bars in the Bar Chart and the pie slices in the Pie Chart. Since the Chart is comprised of two sub-charts, you must pass in an array of properties. For example: [ {colors: ['blue']}, {colors: ['blue','red','green'}] .

Building Dashboard Applications

Javascript Charts are ideal for 'dashboard' applications. You can design a UX component with multiple Javascript Charts each of which displays data on one of the metrics your dashboard is designed to monitor.

In situations where a large number of users are connected to the dashboard, and where you want to update the dashboards frequently, you can use Alpha Anywhere's Web-sockets feature to create an efficient application. Instead of having the UX component make periodic callbacks to the server to refresh the data shown in the dashboard charts, a scheduled CRON job on the server can update data for the dashboard, then when broadcast the data to all of the connected UX components.
 

Speed Typing Glossary - Javascript and Xbasic Editors - You can now define abbreviations that get automatically expanded in the Javascript and Xbasic editors. This can significantly improve your productivity when you are writing Xbasic and Javascript code.

For example, say that in the Javascript editor you frequently type the following code:

var lObj = {dialog.object}.getControl(

You can now define an abbreviation for this code snippet. Every time you type the abbreviation, it is automatically expanded. For example, you might specify that the abbreviation for the above code snippet is .gc.

Every time you type .gc in the code editor, .gc will be replaced with var lObj = {dialog.object}.getControl(.

Watch Video

The replacement text for the abbreviation can be arbitrarily long. It does not have to be a single line of text as in the above example. You can also specify where the insertion point should be placed after the abbreviation has been expanded.

You can also set rules that control when an abbreviation is expanded. For example, you can specify:

• Only expand abbreviations that appear at the start of the line
• Only expand abbreviations that are preceded by a word boundary. For example, if you have defined an abbreviation do (that expands to {dialog.object}) if would be expanded if you typed do after a space character. But would not be expanded if you typed abcdo because the do abbreviation is not preceded by a word boundary.

You can also specify if the abbreviations should be shown in auto-complete (just like auto-complete for functions and variables), as shown in the image below. If you specify that an abbreviation should be shown in auto-complete, you can define an optional description that will also be shown in auto-complete.

To define a glossary while editing either Xbasic or Javascript, right click, and select the Edit glossary command from the menu. The glossary editor is shown below:

Each line shows the abbreviation, expansion for the abbreviation, and expansion options ( S - show in auto-complete, F - expand if first word on a line, W - expand if preceded by a word boundary)

To edit an individual glossary entry, double click on the item, or click the Edit button. The editor is displayed where you can define both the abbreviation and the replacement text. You can also set the options for the glossary item.

email_send_noprofile() Function - Now allows for a blank username or password. The third parameter for email_send_noprofile() is the security mode. The valid options are blank (""), SSL, and TLS. This parameter is now optional.

Flying Start Genie - Row Expanders - The Flying Start Genie allows you to quickly build Grid components for all (or selected) tables in a database. Now, the Genie will automatically detect if there is a relationship between the Grids that are created and it will add a Row Expander to each Grid if that Grid has related Grids.

For example, in the image below which shows the Grid that was created for the Customers table in the sample Northwind database you can see that each row in the Grid has a row expander that shows the Orders for the selected customer. Similarly, the Orders grid has a row expander to show the Order Details for the selected Order.

UX Component - SemiCircularNumberDisplay Control - A new control type is available in the UX component. This control allows you to display a numeric value on a semi-circular chart. It is ideal for using in 'dashboard' type applications. You can configure the color of the control so that it changes depending on the value. For example if a numeric value is in the 'safe' zone, you might set the color to green, and if the value was in the 'danger' zone, you might set the control color to red.

Watch Video - Part 1
Watch Video - Part 2

To add a SemiCircularNumberDisplay control to your UX component, select the [More...] control in the Data Controls section of the UX Toolbox. Like other controls in the Data Controls section of the UX toolbox, the SemiCircularNumberDisplay control has both a .SetValue() and .GetValue() method that allows you to set its value and read its values.

This will display the list of additional control types:

After you add the control to the UX you can configure the properties of the control by clicking on the smart field for Control Properties. This will open a dialog where you can set the properties of the controls.

Properties of note in the builder include:

• Color type - Choices are 'Static', 'Dynamic' and 'Javascript'. 'Static' - a single color is used to display all values. 'Dynamic' - different colors are used for different ranges of numbers (see below for more information), 'Javascript' - you can specify Javascript code to dynamically compute the color.
• Animate - This option is only available if the Color type is set to Static. Specify if the chart is animated when it's value is set.
• Other properties - Allows you to set other properties of the chart not exposed in the builder. The control is based on the RGraph library (see http://RGraph.net for more information) and there are many more properties to control the appearance of the chart than are exposed in this dialog.

Defining Dynamic Colors

When you set the Color type to Dynamic you can define a series of ranges and the corresponding color for each range. Click the smart field for the Values ranges property (shown when the Color type is Dynamic) to open the builder (as shown in the image below).

The builder allows you to define multiple ranges and for each range, you can specify a color.

UX Component - RadioButton - CheckBox Controls - Render as ButtonList - Align - When you set either a Radio Button, or CheckBox control to render as a ButtonList, you can not control the alignment (left or right) of the button labels.

Components - Styles - Customize Colors - Pre-defined Palettes - When you select the 'Alpha' style for a component, you can customize the colors used in the style by simply setting the values of SASS variables.

When you click the smart field for the Customize style colors and fonts property, a dialog is opened, as shown in the image below, where you can set values for each of the SASS variables used in the style.

Now, when you open the Edit Style SASS Variables dialog, a new button appears at the bottom of the dialog that allows you to select a pre-defined palette.

When you click the Use a Pre-Defined Color Palette button, the Palette Selector window is opened, as shown below.

When you select a palette from the list, the colors are applied to the items in the Edit Style SASS Variables dialog. If you want to use the colors, click OK. If you click Cancel, the colors are not applied.

If you have selected a palette, and you want to go back to the base theme with no palette, select <none> from the list.

Setting Min and Max Values at Run-time

The following Javascript snippet shows how you can dynamically set the control's min and max value at run-time.

var max = {dialog.object}.getValue('max');
max = Number(max)
//get a pointer to the control
var obj = {dialog.object}.getControl('semicircularNumber_1');

//set the min and max
obj.rgraphSettings.max = 200;

obj.rgraphSettings.min = 40;

//redraw the control
obj.redraw();

Application Server - Alerts - The Alpha Anywhere Application Server Classic server now has the ability to send administrative alerts by email and SMS. This can be configured on the Logging tab of the settings UI. There is also a Test Alerts button. This will send both a test email and a test SMS, if each are enabled, in order to confirm that the settings entered are working as expected.

NOTE: These comments do not apply to the Alpha Anywhere Application Server for IIS.

For email notifications, all that is required is a recipient email address. There is no email server configuration necessary, as emails will be sent using a special account, AppServerAlerts@alphasoftware.com. Multiple recipients may be specified by separating them with a comma.

For SMS notifications, the customer must have their own Twilio account and provide the appropriate account information in the server's settings, along with the recipient SMS number. This functionality will work with a free Twilio account, but Twilio may impose limits on free accounts. Multiple recipients may be specified by separating them with a comma.

Currently there are 4 different notification levels, detailed below. Each level includes all alerts from levels under it (higher number).

Level 1 - Emergency

(Indicates something that requires immediate attention, as the server is no longer operating normally)

• Server failed to start
• Server terminating abnormally (crashing)
   

Level 2 - Alert

(Indicates something that needs attention very soon, as server functionality will be impacted)

• Server has started in an unlicensed mode

Level 3 - Warning

(Indicates a potential problem)

• Maximum threads are running (server is at full capacity)
• Failed to create new threads

Level 4 - Notice

(Indicates an informational notice)

• Normal server start
• Normal server stop
• Logs automatically rotated

Xbasic - a5_ink_to_png() Function - Convert Ink to a PNG Image - The Ink control (in the UX component) uses a special syntax for the Ink data. The a5_ink_to_png() function converts the ink data to a PNG image.

Syntax

a5_ink_to_png(C ink,N heightInPoints,N widthInPoints,C filename)

Where:

• ink - the Ink data to be converted
• heightInPoints - the height of the PNG image in points (72 points = 1 inch)
• widthInPoints - the width of the PNG image in points
• filename - the filename of the PNG image

Javascript Library - A5.runChain() Function - Run Asynchronous Functions Synchronously - A new function has been added to the Alpha Anywhere Javascript library to run asynchronous functions synchronously.

Many Javascript functions run asynchronously. For example, functions that make Ajax callbacks are asynchronous. In PhoneGap applications, most of the functions are asynchronous.
 

This helper function allows you to run a series of functions (some of which may be asynchronous) synchronously (i.e. the second function does not start executing until the first function has completed, and so on).

Watch Video - Part 1
Watch Video - Part 2

 

Syntax:

A5.runChain(actions,onAllDone,onStop [, context]);

Where:

• actions - an array containing the functions to be executed. Some or all of the functions in the array may be asynchronous.
• onAllDone - function to call when all of the functions in the actions array have completed.
• onStop - function to all if any of the function in the actions array stopped the execution chain.
• context - an optional object to define the scope of the actions. Inside each function that is executed, the this object will be the same as the context. This allows you to pass initial information into the first function and allows each function to set variables on the this object that will be seen by subsequent functions.

Each function in the actions array must take a single object as its input parameter. Each function must call the .next() method of the input object to begin execution of the next function in the actions array. If the function is an asynchronous function, the call to the .next() method would be in the onSuccess callback of the asynchronous function.

The execution chain can be stopped if any function calls the input object's .stop() method.

Example

//define 3 functions you want to run asynchronously

//this is an asynchronous function

function action1(obj) {

    setTimeout(function() {

        console.log('wait 1 second');

        obj.next() // call the next function to be executed

    },1000 );

}

function action2(obj) {

    console.log('this is a synchronous function');

    obj.next()

}

function action3(obj) {

    setTimeout(function() {

        console.log('wait .5 seconds');

        obj.next()

    },500 );

}

//create an array with the functions to executed

var actions = [action1,action2,action3];

//run the actions synchronously

A5.runChain(actions,

    function() { alert('alldone'); },

    function(err) { alert('error: ' + err); }

);

//if we want to pass in values to the chain we can do as follows

var context = {var1: 'value of var1'};

A5.runChain(actions,

    function() { alert('alldone'); },

    function(err) { alert('error: ' + err); },

    context

);

//inside any of the functions we can reference 'this.var1'

//we can also set properties on the 'this' object.

When you run this code, the messages in the console will appear in the following order:

wait 1 second

this is a synchronous function

wait .5 seconds

If you had simply called the functions one after the other, then the messages would have appeared in the following order:

this is a synchronous function

wait .5 seconds

wait 1 second

Installing the Alpha Anywhere IDE on Multiple Machines - Deactivating a License - The Alpha Anywhere IDE license allows you to install the  Alpha Anywhere IDE on as many machines as you want, but you can only use it on one machine at a time.

If you have installed the AA IDE on two machines, for example, and you started the AA IDE on one machine and then exited the AA IDE on that machine and tried to start it on the second machine immediately after exiting the AA IDE on the first machine, this would not be possible because the activation 'lease' would not yet have expired. By default, the activation 'lease' for the AA IDE is 24 hours. (This can be changed in the View, Settings, Preferences menu command)

However, if you select the File, Deactivate License and Exit menu command, on the first machine, you would be able to go to the second machine and start the AA IDE immediately. You would not have to wait until the lease on that machine expired.

UX Component - List Control - Import Data - If a List control in a UX component is based on data from a SQL database you can now upload an Excel or Ascii file (containing CSV data - comma separated values) and then import the data in that file into the table in the SQL database that the List is based on. After the data are imported, the List is automatically refreshed.

NOTE: If a List is based on a stored procedure, you cannot import data.

The data in the uploaded file must use field names that match the column names in the target SQL table.

In the case of a CSV file, the field names are in the first row of data in the file. In the case of an Excel file, the field names are the column heading in the first row of data.

NOTE: In the case of an Excel file, if the file has multiple tabs, the data on the first tab is imported.

Field names in uploaded file cannot contain spaces, or special characters.

To create an Import Action, use Action Javascript and select the Import Data into a List Control from Excel or Ascii file action.

This will open the builder where you can define the define the target List control into which you want to import data.

The properties of note in the builder include:

Target List control name - The name of the List control into which you want to import data. The data are actually imported into the table in the SQL database that the List is based on. Only Lists that are based on SQL databases (and do not use stored procedures for the List query) are eligible targets.

Pre-process uploaded file Xbasic function - After the file has been uploaded you can call an Xbasic function to validate the data before it is imported into the target table. Your Xbasic function gets passed an array with all of the data to be imported. Your code can modify the data in the array or delete array entries that do not meet validation criteria

Maximum records to process - If the uploaded file contains more records that the specified maximum, no data are imported.

Xbasic - Context.Security.AdministrativeCreateUser() Method - Adds a new user with a password.

Normally Context.Security.CreateUser() is used to create users. When the security setting for Reset Password is set require a question and answer, a security question and answer are required to create a user.

This requirement is not practical when an administrative task creates a user.

The AdministrativeCreateUser() method can be used in this case. It does not require a security question and answer even if the security settings require one. Because of this, its use should be limited to pages/code that require administrative access and the application should require the user to set a security question and answer on first login.

Web Control Panel - Node Services Category - The Web Control Panel now has a new category - Node Services. This makes it easier to create Node services that can be called from your Xbasic code.

When the Node Services item has focus, the New button will create a new stub Node service that serves as a helpful starting point for defining a new service.

Once you have defined your Node service, you can call it from your Xbasic code using the node_request_result() function.

For example, say you have define a service called multiply and that this service takes as input x and y. Here is how you could call the service from Xbasic:

dim pIn as p

pIn.x = 4

pIn.y = 3

dim pOut as p

pOut = node_request_result("multiply",pIn)

?pOut.error

= ""  'empty string indicates no errors.

?pOut.result

= 12

Web Control Panel - Node Services Category - The Web Control Panel now has a new category - Node Services - that shows all of the Node services defined in the project.

Node_request() Function - Automatic Node Restart -  If you are in WorkingPreview or LivePreview and you have edited the code in a Node Services definition, when you call node_request() to run the service, the optional  flagRestartNode parameter will automatically be set to .T.. This makes iteratively testing edits to a Node service easier to test. Without a Node restart, edits to the Node service definition would not be picked up by Node.

Node_request_result() Function - A wrapper around the node_request() function, except that instead of returning a JSON string, the JSON is already parsed and the function returns a .result and .error property. If there was no error, the .error property is blank.

Session Folders - The Alpha Anywhere Application Server now uses A5Storage for session files. A5Storage allows for much greater flexibility in storing session data on local disk, network attached storage, Amazon S3, and Azure. This means that the physical folders previously located in a directory named session_folders within the webroot are no longer used in any way and will not be created by the server.

Direct access to these folders has never been supported by Alpha Software, and the Session.Session_Folder and Session.Session_URL properties were deprecated in version 11 and removed in version 12 (Alpha Anywhere). With this update, ServerSetting.SessionFolders has also been removed.

However, some developers may have written custom code to directly access these folders. Any existing code of this type will no longer function as expected and will need to be updated or replaced accordingly.

See https://www.alphasoftware.com/documentation/pages/Server/Guide/Design/Sessions/Storing%20Files%20in%20Sessions.xml for more information on working with files in Sessions.
 

Xbasic - create_table_sql() Function - Excel - You can now pass the name of an Excel file to the create_table_sql() function. This will create a SQL table based on the list of columns in the Excel data and also import the data into the SQL table.

The name of the Excel file is passed in as the fieldList parameter.

Xbasic - sql_import() Function - Excel - You can now pass the name of an Excel file to the sql_import() function. This will import the data in the Excel file into the SQL table.

The name of the Excel file is passed in as the data parameter.

SQL Server Reporting Services - Using Reports Created in SQL Server Reporting Services in an Alpha Anywhere Project - Many organizations use SQL Server Reporting Services (SSRS) and have a number of reports that were developed in SSRS. Using these reports in an Alpha Anywhere application is now possible using the SSRS integration features in Alpha Anywhere.

Watch Video - Part 1
Watch Video - Part 2
Watch Video - Part 3

In order to use SSRS reports in an Alpha Anywhere project you must:

• Create a SSRS connection string that points to a SSRS server
• Link the SSRS reports that you want to use in the Web Project Control Panel

These steps are discussed in more detail below.

Once you have created a link to a SSRS report, the report link can be used just like any other Alpha Anywhere report. You can add the report to the TabbedUI, or you can create actions using Action Javascript to display the report.

Creating a SSRS Connection String

To create SSRS connection string, select the Tools menu when the Web Control Panel has focus and then select the SQL Server Reporting Services Connection strings menu item.

You can then define a new connection string, or edit an existing connection string:

Linking SSRS Reports

To link SSRS reports in your Web Project, go to the Web Projects Control Panel and select the Reports category.

Then click the New button. The dropdown menu shows these choices:

This will bring up a dialog where you can select the SSRS reports you want to link in your Alpha Anywhere project.

Select your SSRS connection string in the Connection String dropdown box. A list of reports defined in the selected SSRS server will be displayed.

NOTE: The first time you connect to a SSRS server, it can take quite a long time before SSRS responds with the list of reports.

Select as many of the listed reports as you want.

Notice that at the bottom of the dialog there is a Preview Reports hyperlink that will allow you to preview any report before you select it. If the selected report uses parameters, you will be prompted for the parameter values.

Links will be created for each of the selected reports. A link is a file in the Web Projects control panel with information about the SSRS report. The filename includes the .ssrs. string in the name just before the .a5rpt extension.

For example:

Once a report has been linked, you can set security on the report as if it were a native Alpha Anywhere report. You can add the report to a TabbedUI, or show the report when a button is clicked by using Open a Report action in Action Javascript.

Publishing Profiles

When you define a publishing profile to publish your application you can specify values for your SSRS connection strings, just as you can for all other types of connection strings (e.g. AlphaDAO, storage, etc.). This means that you can connect to a different SSRS server when you publish your application than you do when you are developing your application.

TabbedUI Component - Search - If a TabbedUI component has a large number of items, it can be difficult for a user to find the item that they want. You can now add a search feature to the TabbedUI to allow users to quickly find the items they are looking form. As the user types into the search box a filtered list of the matching items is displayed (see second image).

Watch Video

In the image below the search feature has been turned on, but the user has not yet typed into the search box.

In this image the user has typed a string into the search box and all of the matching items are displayed.

To turn the search feature on, go to the TabbedUI Properties pane in the TabbedUI builder and check the Enable search property.

Once you have turned on the search feature, there are a number of other properties you can set.

UX Component - Action Javascript - Get Server-side Data - A new action has been added to Action Javascript. The purpose of the action is to get server-side data and return the data to the client where you can then further process the data with Javascript code. For example, you might use the data returned to populate a List control, a dropdown box, a SpinList etc.

The builder for the action is shown below:

The server-side data can be obtained by performing a query against a SQL database, or by executing a Xbasic function (which can, in turn, call web services - REST or SOAP) to get the data that should be returned to the client.

The options for the Query type parameter are:

• SQL query - A query any SQL database that Alpha Anywhere can connect to.
• Nested SQL query - A query against a SQL database that will return a complex JSON document with nested arrays. For example an array of customers, for each customer, a nested array of orders, for each order, a nested array of order details.
• Xbasic - An Xbasic function that will execute when the action is run. The Xbasic function will return an array of data (in JSON format). The JSON might come from a REST or SOAP API called by the Xbasic function.

The onSuccess property allows you to define Javascript to execute once the data is received by the client. The data that is received by the client will be stored in a variable called:

{dialog.object}._serverSideData

UX Component - List Control - Dynamic Images - Image Sequences - Client-side - You can now specify dynamic images when you define a dynamic image field to a List and specify that the dynamic image computation is server side.

Xbasic - SQL_Import() Function - Import data into a SQL Table - The sql_import() function is a helper function that imports CSV or JSON data into a SQL table.

NOTE: The function is called a 'helper' function because it simply wraps the low level AlphaDAO methods for doing a bulk insert into a SQL table.

Syntax

p result = sql_import(c connectionString, c tableName, c tableOwner, c data [, L replicateIdentity [, c fieldMap]])

Where

• result - an object with these properties: error - either .t. or .f., depending on whether the operation succeeded and errorText - description of the error
• connectionString  - the connection string (either a named or explicit connection string. if named, the ::name:: prefix is optional)
• tableName - the name of the table into which you want to import data
• tableOwner - the owner of the table into which you want to import data.
• data - the data to be imported. Can either be in CSV (comma separated value) or JSON format. See examples
• replicateIdentity - .t. or .f. - defaults to .f.. Should only be set to .t. if you are importing into an empty table. If .t. then values for the auto-increment primary key (if any) that are supplied in the input data are explicitly set in the target table.
• fieldMap - If the columns in the input data do not match the field names in the target SQL table you can specify a map. The map is a crlf delimited string of field pairs. See example below.

Example fieldMap

Assume that the input data is as follows

fname,lname

fred,smith

john,jones

Assume that the target table has column names of firstName and lastName.

You would need to specify the following fieldMap:

fname=firstName

lname=lastName

Example:

dim cs as c
cs = "mydata"
tablename = "table1"
data = <<%str%
id,name,notes,dob,number
1,"Jones, Amy","Here are some notes",1992-12-18,34.56
%str%

'replicateIdentity = .f.
map = "name=fullname"
 

dim p as p
p = sql_import(cs,tablename,"", data,replicateIdentity,map)
 

?p.error

= .f.

UX Component - Map Control - Action Javascript - Google Map Methods - Two new actions have been added to the Google Map Methods action

• Get a pointer to the Google Map object - allows you to get a pointer to the underlying Google Maps object. Useful if you are trying to implement some code you found while reading the Google Maps API documentation.
• Add KML Layers to map - Allows you to add a KML layer to your map.

Xbasic - what3words() Function - Add support for the what3words service. Allows you to translate an address or location to a what3words address, or a what3words address to a location. For more information on what3words go to www.what3words.com.

Syntax

p result = what3words(c key, c mode, c input)

Where

• result -  object with result from the call.
• key - your what3words API key
• mode - can be wordstolocation - converts a what3words address to a location (lat, lng), locationtowords - converts a location (lat,lng) to a what3words address, or addresstowords - converts a standard address to a what3words address.

Examples

key = "Your api key"

mode = "wordstolocation"

input = "traps.plan.code"

dim p as p

p = what3words(key,mode,input)

?p.lat
= 42.423661
?p.lng
= -71.213213

mode = "addresstowords"
input = "70 blanchard road, burlington ma usa"

dim p as p
p = what3words(key,mode,input)
?p.words
= "newly.slams.roses"
 

Xbasic - create_table_sql() Function - Create a table in a SQL database.

Syntax

P result = create_table_sql(c fieldList,c connectionString,c tableName [, c mode])

Where

• result - an Object with these properties: "hasError" - (true or false), "errorText" - description of the error, "sqlStatement" - the SQL statement that was generated to create the table
• fieldList - a crlf string or a JSON string defining the fields in the table to be created. See below for more information.
• connectionString - The connection string to the database where you want to create the SQL table. Can be either a named connection string, or an explicit connection string.
• tableName - Name of the table to create
• mode - Can be "skip" - does not create table if there is an existing table, or "overwrite" - overwrite any existing table

The fieldList parameter can be either a JSON array of objects defining each field, or a crlf delimited list of pipe delimited properties.

Example of a CRLF delimited fieldList:

id|N|6|0|AutoIncrement

name|c|20

dob|d

notes|m

In this example a primary key (that is not an AutoIncrement fields) is defined

id|c|6||PrimaryKey

name|c|20

dob|d

notes|m

When defining a primary key you can designate multiple columns:

firstname|c|20||PrimaryKey

lastname|c|20||PrimaryKey

dob|d

notes|m

Example of a JSON fieldList:

[

    {"name": "id", "type": "numeric", "size": 6, "decimals" : 0, "autoIncrement": true},

    {"name": "name", "type": "character", "size": 20},

    {"name": "dob", "type": "date"},

    {"name": "notes", "type": "memo"}

]

In this next example a primary key (that is not an Auto Increment field) is defined:

NOTE: Multiple fields can have the 'primaryKey' attribute set to true.

[

    {"name": "id", "type": "character", "size": 6,  "primaryKey": true},

    {"name": "name", "type": "character", "size": 20},

    {"name": "dob", "type": "date"},

    {"name": "notes", "type": "memo"}

]

Xbasic - JSON_shred() Function - Converts a complex JSON string representing an array of objects with nested arrays) into individual arrays that do not have any nested arrays.

Syntax:

c result = JSON_shred( c JSON, c schema [, c ParentArrayName])

where

• result - the output from the JSON_shred() function
• JSON - the JSON to be shredded
• schema - the description of the 'shape' of the input JSON and the definition of any 'key' fields that should be added to the result.
• ParentName - the name of the top level array in the result.

Consider the following JSON string:

[
	{"Firstname": "John", "Lastname" : "Smith", "City" : "Boston", "State" : "MA", "Children": [
		{"Name" : "Callie", "Age" : 5},
		{"Name" : "Griffin", "Age" :3},
		{"Name" : "Luke", "Age" : 1}
		]
	}, 
	{"Firstname": "Henry", "Lastname" : "Rhodes", "City" : "New York", "State" : "NY", "Children": [
		{"Name" : "Howard", "Age" : 15},
		{"Name" : "Robert", "Age" : 11}
		]
	}
]
			
			

The JSON is an array in which each object in the array has a nested array of 'children'.

This JSON can be 'shredded' to produce this result:

			
{
    "__top": [
        {
            "Firstname": "John",
            "Lastname": "Smith",
            "City": "Boston",
            "State": "MA"
        },
        {
            "Firstname": "Henry",
            "Lastname": "Rhodes",
            "City": "New York",
            "State": "NY"
        }
    ],
    "Children": [
        {
            "Name": "Callie",
            "Age": 5
        },
        {
            "Name": "Griffin",
            "Age": 3
        },
        {
            "Name": "Luke",
            "Age": 1
        },
        {
            "Name": "Howard",
            "Age": 15
        },
        {
            "Name": "Robert",
            "Age": 11
        }
    ]
}

The result is an object with two arrays: __top and Children. Notice however, that since the 'Children' array is no longer nested inside each object in the top level array, the linkage between the entries in the 'Children' array and their parent has been lost.

In the above example, the JSON_shred() function was called using a schema that did not specify that any key fields should be added to the Children array.

The schema used to produce the above result was:

	
[
    {
        "Children" : [
            {
            }
        ]
    }
]

Notice how the  schema defines the 'shape' of the input JSON but does not specify that any additional 'key' fields should be added to the Children array.

In order not to loose the relationship between each object in the Children array to its parent, a key field must be added to each object in the Children array that points to its parent record. The desired output from the shredding operation is shown below:

	
{
    "__top": [
        {
            "Firstname": "John",
            "Lastname": "Smith",
            "City": "Boston",
            "State": "MA"
        },
        {
            "Firstname": "Henry",
            "Lastname": "Rhodes",
            "City": "New York",
            "State": "NY"
        }
    ],
    "Children": [
        {
            "key": "John Smith",
            "Name": "Callie",
            "Age": 5
        },
        {
            "key": "John Smith",
            "Name": "Griffin",
            "Age": 3
        },
        {
            "key": "John Smith",
            "Name": "Luke",
            "Age": 1
        },
        {
            "key": "Henry Rhodes",
            "Name": "Howard",
            "Age": 15
        },
        {
            "key": "Henry Rhodes",
            "Name": "Robert",
            "Age": 11
        }
    ]
}

Notice that each record in the 'Children' array now has a property called 'key' that points to its parent record. To obtain the above result, the following schema is used:

	
[
    {
        "Children" : [
            {
            	"key": "{../Firstname} {../LastName}"
            }
        ]
    }
]

The schema specifies that each object in the 'Children' array should have a property called 'key' whose value is the "Firstname' and "Lastname" property in the immediate parent object. The syntax used to specify a value from a parent object is ../.  You can reference properties at the grand parent level using ../../, and so on.

Here is a more complex example that shows multiple levels of nested arrays in the input JSON. Notice that the "Hobbies" array is an array of strings, not an array of objects. This array is converted into an array of objects in the result.

	
[
	{"Firstname": "John", "Lastname" : "Smith", "City" : "Boston", "State" : "MA", "Children": [
		{"Name" : "Callie", "Age" : 5},
		{"Name" : "Griffin", "Age" :3, "Hobbies" : ["Leggo","Star Wars"]},
		{"Name" : "Luke", "Age" : 1}
		]
	}, 
	{"Firstname": "Henry", "Lastname" : "Rhodes", "City" : "New York", "State" : "NY", "Children": [
		{"Name" : "Howard", "Age" : 15},
		{"Name" : "Robert", "Age" : 11, "Hobbies" : ["Soccer"]}
		]
	}
]		

Here is the schema that could be used to shred the above JSON:

	
[
    {
        "Children" : [
            {
            	"Hobbies" : [ 
            		{ 
            			"hobbyKey" : "{../../Firstname} {../../Lastname}|{../Name}" 
            		}
            	],
            	"key": "{../Firstname} {../LastName}"
            }
        ]
    }
]

And here is the resulting output from the shredding operation:

	
{
    "__top": [
        {
            "Firstname": "John",
            "Lastname": "Smith",
            "City": "Boston",
            "State": "MA"
        },
        {
            "Firstname": "Henry",
            "Lastname": "Rhodes",
            "City": "New York",
            "State": "NY"
        }
    ],
    "Children": [
        {
            "key": "John Smith",
            "Name": "Callie",
            "Age": 5
        },
        {
            "key": "John Smith",
            "Name": "Griffin",
            "Age": 3
        },
        {
            "key": "John Smith",
            "Name": "Luke",
            "Age": 1
        },
        {
            "key": "Henry Rhodes",
            "Name": "Howard",
            "Age": 15
        },
        {
            "key": "Henry Rhodes",
            "Name": "Robert",
            "Age": 11
        }
    ],
    "Hobbies": [
        {
            "hobbyKey": "John Smith|Griffin",
            "__value": "Leggo"
        },
        {
            "hobbyKey": "John Smith|Griffin",
            "__value": "Star Wars"
        },
        {
            "hobbyKey": "Henry Rhodes|Robert",
            "__value": "Soccer"
        }
    ]
}

PhoneGap App Builder - PhoneGap CLI Build Option - A new option has been added to the PhoneGap App Builder that allows the developer to select and use either PhoneGap Build or a local install of the Cordova CLI (Command Line Interface) to build a PhoneGap App.

Android builds are supported on PC's running Windows and iOS builds are supported on a Mac with Xcode. Using the CLI allows the developer to use the platform's native development tools to build and debug Cordova apps. This also allows the use of plugins that PhoneGap Build does not support because PhoneGap Build does not support the use of plugin hooks.



For the full documentation on the PhoneGap/Cordova CLI Builder, see PhoneGap/Cordova CLI Builder

For a video overview on using the PhoneGap/Cordova CLI Builder, see PhoneGap/Cordova CLI Builder Video Overview

Xbasic - CURL Object - Auto-complete - When you define a CURL object in Xbasic, you now have auto-complete for all of the options available to the .SetOpt() method.

For example:

dim c as extension::curl

c.setOpt(

As soon as you type the opening (, the bubble help instructs you to right click on the argument value (as shown in the image below) to get a list of the options for the .setOpt() method.

UX Component - FormView Control - Lookup Fields - You can now define lookup fields in the FormView. This allows you to display 'friendly' values in the Form (e.g. product name, rather than product id).

To define a Lookup field, go to the Fields tab in the FormView builder and check the Has Lookup value property.

You can then define the Lookup. The lookup data source can be a List control or a Javascript function.

TIP: You may want to use the client-side data cache or a query against a SQLite database (in a PhoneGap application) as the data source for your Lookup. This requires a two-step process because reading data from the client-side data cache, or from a SQLite database can only be done asynchronously. Therefore you must first execute some code that reads the client-side data cache or executes a SQLite query and puts the data in a variable in memory. You can then define the Lookup in the FormView builder to use the Javascript Function option, performing the lookup against the data you have loaded into memory.

Web Project Control Panel - Automatic Refresh - By default every time the list of files in your Web Project changes, or a file is edited, the Web Project Control Panel will refresh. However, if your project contains a very large number of files  (several thousand), then refreshing the Control Panel can be slow and you might want to turn off the automatic refresh of the Control Panel and only refresh it when needed.

You can turn off automatic refresh by clicking on the More... button in the Web Control Panel and selecting the Set Control Panel refresh options... menu entry.

If you turn off automatic refresh, a Refresh button will be shown in the Web Control Panel. Click this button to refresh the Control Panel.

UX Component - List Controls - Dynamic Images - Image Sequence - When you add a server-side dynamic image to a List control, you can now specify that you want to use an image sequence for the image.

UX Component - Map Control - Adding Multiple Markers to a Map Control Using Client-side Data - Action Javascript has an action to add multiple markers to a map. The data that defines the latitude/longitude for each marker on the map (and also for the marker titles, details etc). has previously been server-side data. Now, you can specify that the data should be client-side data.

In the case of server-side data you specify the name of a Data Series that specifies the properties for each marker. In the case of client-side data, the data can come from a Javascript function, a List control, the client-side Data Cache, or, in the case of a PhoneGap application, by querying a SQLite database on a device.

Watch Video - Part 1
Watch Video - Part 2
Watch Video - Part 3
Watch Video - Part 4
Watch Video - Part 5

Download Component

To specify that the Google Map Method (UX Component) / Add multiple markers to the map action should use client-side data, set the Data type property to ClientSideData. You can then specify whether the client-side data comes from a Javascript function, or from data in a List control.

In the case where you specify the name of a Javascript function, you specify the name of a Javascript function (which must return an array of objects - each object has properties that must include the marker latitude and longitude values). You must also specify the names of the properties in the data returned by the Javascript function.

For example, assume that you specify the name of a Javascript function that returns data like this:

			
[
		{
			"name": "COYOTE FLATS",
			"city": "BISHOP",
			"state": "CA",
			"latitude": "37.20203",
			"longitude": "-118.47629"
		},
		{
			"name": "LOST HILLS SHERIFF\\'S STATION",
			"city": "CALABASAS",
			"state": "CA",
			"latitude": "34.14167",
			"longitude": "-118.5262"
		},
		{
			"name": "GOLDSTONE /GTS/",
			"city": "BARSTOW",
			"state": "CA",
			"latitude": "35.35053",
			"longitude": "-116.88837"
		}
]
			
			

In this case the property names that you specify in the Javascript properties property would be:

name,city,state,latitude,longitude

NOTE: If you want to use data from the client-side Data Cache, or (in the case of a PhoneGap application) data from a query against a SQLite database, you need to use a two-step process because reading data from a Data Cache (or a SQLite database) is an asynchronous action. Therefore your Javascript must read the Data Cache, or execute the SQLite query (you can use Action Javascript for this) and in the on success function for the action, you must put the data you have just read into a variable in the UX object (for example {dialog.object}._mapData) and then call the Action Javascript action to add the markers to a map using the Javascript function option. The Javascript function will read the data from the variable that contains the data.

Xbasic - Classes - The Web Control Panel now exposes a new category - Xbasic Class - that allows you to defined Xbasic classes that can then be used in any server-side Xbasic code.

To use an Xbasic class in your Xbasic code you use the loadClass() function to load the definition and then you can DIM and instance of the class.

For example:

dim flag as l
flag = loadClass("helloclass")
dim h as helloclass

NOTE: It is not strictly necessary to use the loadClass() function to load the class before DIMming and instance of the class. If the DIM statement fails, Xbasic will then try to load the class itself by searching for the class definition. But this will add a short delay to your code while Xbasic tries to resolve the class. Therefore it is recommended that you explicitly load the class before using it. Also, if you make an edit to the class definition, the edit will be seen immediately if you explicitly load the class.

Xbasic - loadClass() Function - Loads a class definition.

Syntax

L flag = loadClass(c className)

Where

• flag = .t. or .f. depending on whether the class was successfully loaded or not
• className = name of the Xbasic class filename (with or without the .a5xbclass extension).

UX Component - Integrated Login - Server-side onLogin Event - Enhancements have been made to the server-side onLogin event so the following actions in the onLogin event handler are now supported

• setting argument values
• setting control values using the e.control.controlname syntax
• setting property values using the e._set syntax.

For example:

e.arguments[e.arguments.ArgumentNumber("Arg1")].data = "Portugal"

e._set.field1.value = "foo"

e.control.field2 = "bar"
 

Web Components - Manifest Files - Using Source Control - Most web components use a special support file with a _a5wcmp_manifest file extension. When a component is published, the process checks for a manifest file built at the same time as the requested component. The publish process uses this manifest file to determine what other files need to be published to run the component.

Previously, the file name for each 'manifest' file contained a timestamp string to synchronize the file with its parent component. This caused a problem if the component files were stored in a source control system. (See release notes for 'Grid Component - Compiled Files - Using Source Control' for a complete explanation).

The new process stores the linking timestamp internally in the two files, and the manifest filename never changes. It can now be stored in a source control system with its parent component.

This new naming convention is only applied when a component is edited and resaved, or when the manifest files are updated by a bulk process. Existing components with the legacy file naming will still function normally. Some components such as login and navigation components do not use the new process as they do not build a manifest when saved.

UX Component - Alignment Container - The Alignment container makes it easy to left, center, or right align a series of controls.

When you select an Alignment container you can set standard set of properties for  container. If you set the alignment to left or right, then you can also set an offset property to control distance of the controls from the left or right edge.

All of the controls in an Alignment Container render on their own line, regardless of whether or not a break follows the control.

If you want multiple controls to be on the same line, you must wrap the controls in a container and then the Alignment container will align the enclosing container.

The image below shows how the above definition renders (but with the alignment set to Center, not Left as shown in the image).

The width of the Alignment container has been set to 100% and the width of the first three textbox controls have been set to 50%, 75% and 33% respectively. As you can see the controls are all horizontally centered  within the container.

The txt4 and txt5 controls both appear on the same line because they are wrapped in  standard container whose width has been set to 2.5inches. The container itself, which has a red border, is horizontally centered.

UX Component - PhoneGap - New Sample Template - PhoneGap - Sound Effects using Native Sounds - A new sample template component has been added that shows how you can add sound effects to your application using the PhoneGap Low Latency Audio plugin. When you create a new UX component you will see the template listed in the list of available samples.

UX Component - FormView Control - List DataSource - {dialog.object}.formViewCommit() Method - Commit Dirty Fields Only - You can now specify that only fields that were edited should be committed to Form's data source. Only applies if the Form's data source is a List control.

Syntax

var flagOnlyCommitDirtyFields = true;

{dialog.object}.formViewCommit('{form.id}',flagOnlyCommitDirtyFields);

Xbasic - csv_to_json() - Convert a CSV string to JSON.  Fields must be comma delimited. First row must be fields names. If a field contains a comma, enclose field in quotes. If a field contains quotes, escape quotes using two consecutive quotes

Example

dim txt as c
txt = <<%txt%
ticker,name,price:N,change:N,mktcap,chgPct
"AAPL","Apple Inc.",402.215,"-24.025",377.7B,"-24.025 - -5.64%"
"GOOG","Google Inc.",780.37,"-13.00",257.3B,"-13.00 - -1.64%"
%txt%
 

? csv_to_json(txt)
= [
{ "ticker" : "AAPL" , "name" : "Apple Inc." , "price:N" : "402.215" , "change:N" : "-24.025" , "mktcap" : "377.7B" , "chgPct" : "-24.025 - -5.64%"} ,
{ "ticker" : "GOOG" , "name" : "Google Inc." , "price:N" : "780.37" , "change:N" : "-13.00" , "mktcap" : "257.3B" , "chgPct" : "-13.00 - -1.64%"}
]

UX Component - onLogin and onLogout Server-side Event - Setting state variables. You can now use the

e._state.varname = varvalue

syntax to set the value of state variables in the server-side onLogin and onLogout event. Keep in mind that if the UX is set to do a full refresh on logout, setting state variables in the onLogut event is meaningless.

Action JavaScript - Stripe Checkout - A5.stripe.getEmbeddedStripeResults Function A new function has been added to Stripe Checkout to handle a unique situation that occurs when the Stripe Checkout control is used within an embedded UX component that is reloaded after its was initially loaded The new function may be called in the onStripeCheckoutComplete event.

Example: onStripeCheckoutComplete event handler

var e = {};
if ({dialog.object}.getStripeResults) {
    e = {dialog.object}.getStripeResults();
} else {
    e = A5.stripe.getEmbeddedStripeResults();
}


 

Videos

Features

Xbasic - Javascript Web Tokens (JWT) - Additional Options - Additional options have been added to the Xbasic classes for generating Javascript Web Tokens. For more details refer to the documentation.

IIS Application Server - PKI Authentication - Support has been added for PKI authentication. For more details refer to the documentation.

Watch Video - Part 1
Watch Video - Part 2
 

Xbasic - Extension::JSON Class - New methods - New methods have been added to the extension::JSON class to make it easier to extract data from a JSON object.

NOTE: You can generally easily extract data from a JSON string by parsing the JSON to an Xbasic dot variable, using the json_parse() method. But if the JSON has property names that are not valid Xbasic variable names, then you cannot parse the JSON. Also, parsing an extremely large JSON string could be slow. The methods described here do not require the JSON to be parsed into an Xbasic dot variable, and work for all types of JSON property names.

Methods 1

extension::JSON::OffsetToPath(json,offset[,base])

where:

• json - string of JSON data
• offset - number - position in the JSON string - e.g. 1345 (character 1345 in the JSON string)
• base - 0 for Javascript and 1 for Xbasic (since Xbasic arrays are 1 based)

 Returns a 'path' to the JSON element that contains the text at the specified offset.

Example:

Assume that json is a variable that contains the sample JSON shown below

?extension::JSON::OffsetToPath(json,540,1)
= "[1].orders[1].orderItems[1]"
 

This means that the path in the JSON to the element that contains the text at position 540 is:

[1].orders[1].orderItems[1]

Method 2

extension::JSON::PathToOffset(json,path[,base])

where:

• json - string of JSON data
• path - path to an element in the JSON string
• base - 0 for Javascript and 1 for Xbasic (since Xbasic arrays are 1 based)

Returns the offset in the JSON string for the element specified by the path.

Example:

Assume that json is a variable that contains the sample JSON shown below

?extension::JSON::PathToOffset(json,"[1].orders[1].orderItems[1]",1)
= 355

 

Method 3

extension::JSON::PathExtract(json,path[,base])
 

where:

• json - string of JSON data
• path - path to an element in the JSON string
• base - 0 for Javascript and 1 for Xbasic (since Xbasic arrays are 1 based)

Extracts a JSON element for a specified path

Example:

?extension::JSON::PathExtract(json,"[1].orders[1].orderItems[1]",1)

= {
	"OrderID": "10643",
	"ProductID": "28",
	"Quantity": "15",
	"UnitPrice": "45.6"
}

Sample JSON string for above examples:

		
		[
        {
            "CustomerID": "ALFKI",
            "CompanyName": "Alfreds Futterkiste",
            "orders": [
                {
                    "OrderID": "10643",
                    "CustomerID": "ALFKI",
                    "OrderDate": "09/25/1995 12:00:00 00 am",
                    "orderItems": [
                        {
                            "OrderID": "10643",
                            "ProductID": "28",
                            "Quantity": "15",
                            "UnitPrice": "45.6"
                        },
                        {
                            "OrderID": "10643",
                            "ProductID": "39",
                            "Quantity": "21",
                            "UnitPrice": "18"
                        },
                        {
                            "OrderID": "10643",
                            "ProductID": "46",
                            "Quantity": "2",
                            "UnitPrice": "12"
                        }
                    ]
                },
                {
                    "OrderID": "10692",
                    "CustomerID": "ALFKI",
                    "OrderDate": "11/03/1995 12:00:00 00 am",
                    "orderItems": [
                        {
                            "OrderID": "10692",
                            "ProductID": "63",
                            "Quantity": "20",
                            "UnitPrice": "43.9"
                        }
                    ]
                },
                {
                    "OrderID": "10702",
                    "CustomerID": "ALFKI",
                    "OrderDate": "11/13/1995 12:00:00 00 am",
                    "orderItems": [
                        {
                            "OrderID": "10702",
                            "ProductID": "3",
                            "Quantity": "6",
                            "UnitPrice": "10"
                        },
                        {
                            "OrderID": "10702",
                            "ProductID": "76",
                            "Quantity": "15",
                            "UnitPrice": "18"
                        }
                    ]
                },
                {
                    "OrderID": "10835",
                    "CustomerID": "ALFKI",
                    "OrderDate": "02/15/1996 12:00:00 00 am",
                    "orderItems": [
                        {
                            "OrderID": "10835",
                            "ProductID": "59",
                            "Quantity": "15",
                            "UnitPrice": "55"
                        },
                        {
                            "OrderID": "10835",
                            "ProductID": "77",
                            "Quantity": "2",
                            "UnitPrice": "13"
                        }
                    ]
                },
                {
                    "OrderID": "10952",
                    "CustomerID": "ALFKI",
                    "OrderDate": "04/15/1996 12:00:00 00 am",
                    "orderItems": [
                        {
                            "OrderID": "10952",
                            "ProductID": "6",
                            "Quantity": "16",
                            "UnitPrice": "25"
                        },
                        {
                            "OrderID": "10952",
                            "ProductID": "28",
                            "Quantity": "2",
                            "UnitPrice": "45.6"
                        }
                    ]
                },
                {
                    "OrderID": "11011",
                    "CustomerID": "ALFKI",
                    "OrderDate": "05/09/1996 12:00:00 00 am",
                    "orderItems": [
                        {
                            "OrderID": "11011",
                            "ProductID": "58",
                            "Quantity": "40",
                            "UnitPrice": "13.25"
                        },
                        {
                            "OrderID": "11011",
                            "ProductID": "71",
                            "Quantity": "20",
                            "UnitPrice": "21.5"
                        }
                    ]
                }
            ]
        }
    ]


		
		

Sample Xbasic script that shows an Xdialog to show how these methods can be used:

'sample.json contains some sample json data						
dim json as c = file.to_string("C:\data\sample.json")

dim def.text as c = json
dim def.object as p
dim selection as c
dim subselect as c
ui_dlg_box("JSON",<<%dlg%
{watch=def.object.get_selection_start(.t.)!cursor}
[%M;K%.100,20def];
Path;
[.100path] <copy<;
[.100selection] <select>;
[%M;K%.100,5subselect];
%dlg%,<<%code%
if a_dlg_button = "cursor" then
	a_dlg_button = ""
	dim pos as n = def.object.get_selection_start(.t.)
	path = extension::JSON::OffsetToPath(strtran(def.text,crlf()," "),pos)
else if a_dlg_button = "copy" then
	a_dlg_button = ""
	selection = path
else if a_dlg_button = "select" then
	a_dlg_button = ""
	dim pos as n = extension::JSON::PathToOffset(strtran(def.text,crlf()," "),selection)
	if pos < 1 then		
		dim subselect as c = extension::JSON::PathExtract( strtran(def.text,crlf()," "),selection)
		def.object.select(pos,len(subselect) )
		def.object.show_caret()
	else
	   ui_msg_box("","Not found")	
	end if	
end if
%code%)						
					

UX Component - Client-Side Properties - On Get Value and On Set Value - Two new client-side properties have been added for Data Controls in a UX component.

• On Get Value Javascript - fires when the {dialog.object}.getValue() method is called. Allows you to transform the value returned by the method.
• On Set Value Javascript - fires when the {dialog.object}.setValue() method is called. Allows you to transform the value used to set the control's value.

In both cases, your Javascript can reference a variable called value and must return a value. For example, in the following example, the .getValue() method will return the upper case version of the control's value

return value.toUpperCase()

These methods can be used to translate a stored value into a display value and vice versa. For example, you might want to display a part description, but store the part number. The data used to to the translation might be stored in a client-side data cache.

UX Component - PhoneGap - Cordova-Open Plugin - The PhoneGap genie now exposes the Cordova-Open plugin. This plugin allows you to open files using their associated native application. For example, if you open a file with a .pdf extension the plugin will open the file using the native PDF application on the device. If you open a file with a .mov extension, the plugin will open the file using the native video player on the device.

The Cordova Open plugin is selected in the PhoneGap genie as shown in the image below.

There are many use cases for the Cordova-Open plugin, but PDF files is perhaps the most compelling use case. Displaying PDF files in a mobile application can be tricky because the browsers on mobile devices do not have built-in PDF viewers as is typical with desktop browsers.

Another great use case for this plugin is a mobile app that downloads multiple files (pdf, video, audio, excel, word, etc.) and then stores these files in the filesystem on the device so that they can be viewer later when the device is no longer connected to the internet. For more information on techniques for downloading files to a mobile device, see this topic in the Tips section: Downloading Files to a Mobile Device.

A new action in Action Javascript (PhoneGap - Open File with Native Application) makes it easy to use the Cordova-Open plugin in mobile applications.

The image below shows how a PDF file appears in the Native PDF viewer on an iPhone (in this case the PDF file was created by generating a report and saving the report output to a PDF file). Notice the Done button that will return you to the app when you close the Native Viewer.

UX Component - Action Javascript - PhoneGap - Open File with Native Application Action - This action allows you to open a file on a mobile device using the associated native application.

Watch Video - Part 1
Watch Video - Part 2
Watch Video - Part 3

NOTE: You can only use this action in a PhoneGap application. The PhoneGap application must load the Cordova Open plugin.

The action allows you to:

• Open a file that is already present in the file system of the mobile device
• Open a file that is remote.
• Open a file that is dynamically created by making an Ajax callback to the server
• Open a PDF report that is created by making an Ajax callback to the server to run a report and save the report output as a PDF file.

When you select the PhoneGap - Open File with Native Application action in Action Javascript, the following dialog is shown:

• File is remote - specify if you want to open a local file, or a remote file (i.e. a file that is on a remote server)
• Filesystem part - the part of the device filesystem where the file is stored. You can specify a Javascript function to return the filesystem part by prefixing the name of the Javascript function with javascript:, For example javascript:getFileSystemPart.
• Filename - the name of the file you want to open. This can include a relative path if the file is stored in a sub-directory. E.g. PDF/mypdffile.pdf. You can also specify a Javascript function to return the filename by prefixing the name of the Javascript function with javascript:, For example javascript:getFileName.

If you specify that the file is remote, you must specify the File URL.

• File URL - the URL of the file you want to open. For example: http://alphafiles.s3.amazonaws.com/pdffile1.pdf. If the file is stored in the webroot of the Application Server, you can specify a relative filename. For example: pdffile1.pdf. You can specify a Javascript function to return the URL by prefixing the name of the Javascript function with javascript:, For example javascript:getFileURL.
• Make Ajax callback to get the file to view - Specify if an Ajax callback should be made to dynamically create the file that you want to view on the mobile device.

If you specify that you want to make an Ajax callback to get the file to open, you must specify the Ajax callback type

• Ajax callback type - can either be UserDefined or Report. Choose UserDefined if you want to create your own Xbasic function to handle the callback. Choose Report if you want to run a Report that you have defined in your web project and save the report as a PDF file.
• Xbasic function - the name of the Xbasic function that will handle the Ajax callback. In addition to generating the file you want to view on the mobile device, your Xbasic function must return Javascript to set these variables:
  
  {dialog.object}.__filenameNativeViewer - the URL of the file you want to view.
  {dialog.object}.__filenameFriendlyNativeViewer - the friendly name for the file that will be displayed in the title bar of the Viewer app.
  
  TIP: To see an example of how these variables should be set by your Xbasic function, click the smart field for the Xbasic function property. Then click the Show function prototype button.