CapeSoft Logo

CapeSoft NetTalk
Upgrading to NetTalk 9

Download Latest Version
Installed Version Latest Version

NetTalk Upgrade to NetTalk 9

Note: NetTalk Web Services requires xFiles version 2.86 or later

Introduction

This document works through the major changes between NetTalk 8 and NetTalk 9. It is designed for users, currently experienced with NetTalk 8 to quickly identify and use the new features in NetTalk 9. It covers things that are likely to break when you upgrade your app, and instructions on how to correct the application to allow for a smooth upgrade. It also covers other new features which you may wish to make use of in your application.

Quick Bits

The goal of this section is a quick overview of things that have changed since NetTalk 8 which experienced NetTalk 8 users will want to know about. Since there are a few changes in NetTalk 9 which invalidate things that were true in NetTalk 8, and unlearning previously sound information and habits is hard, please pay particular attention to this section.

Browser Support

Support for IE7 is officially dropped in NetTalk 9. This is due to IE7 support being discontinued by jQuery UI.
On the other end of the spectrum the Microsoft Edge browser has been added to the user agent list etc.

Naming

With NetTalk 7, NetTalk split into two levels, NetTalk Lite and NetTalk. In version 9 there are now three levels, NetTalk Desktop, NetTalk Server and NetTalk Apps.

NetTalk Desktop (Desktop)

Contains
  • All NetAuto classes (NetRefresh, NetAutoClose and so on)
  • NetSimple Server and NetSimple Client classes
  • All "Client" classes (Email, Ftp, WebClient, SMPP etc)

NetTalk Server (Server)

This includes everything that was included in NetTalk 8. More specifically;
  • NetTalk Lite
  • NetWebServer templates and classes
  • Creates Web Apps and WEB API procedures
  • All web devices are targeted including mobile devices using web apps "mobile mode".

NetTalk Apps (Server)

This level is new to NetTalk 9. It contains all of NetTalk Server plus templates and classes for creating disconnected web apps - ie apps that can be packaged and run on devices (including mobile devices) which do not need real-time access to the server. Specifically;
  • Generates JavaScript for running apps without connecting to the server
  • Supports Local Storage in the browser.
  • Includes JavaScript code for synchronizing local data back to a NetWebServer API.

New Functionality

Desktop

NetSimple (Server)

Desktop

Email

Desktop

Web Client

Server

Wizard

The wizard has been improved and now also supports the creation of API apps, Sync Apps and Mobile Apps.
Server

WebServer Global Extension

  • Added Mobile and Apps tab of settings on second global extension.
Server

WebServer

  • Web Sockets
  • Server Name Indication (SNI) support added.
  • Popup Animations when browses, forms and calendars are opened supported.
  • Host Variables
  • Web server procedure: Buttons on Performance tab to quick-set settings
  • Comments added to some DivHeaders and DivFooters in generated HTML
  • Radio Selection for browse rows has been deprecated and removed.
  • Renamed NetWebServerWorker class to NetWebServerWorkerBase
  • New RenameValue method
Server

Web API Server

  • Support for Session ID as API request Data
  • Support For SYNC as a built-in server process
  • Support REST call of method directly
Apps

Web Server

  • Support for Local Storage

Changes Required to Convert your App from NetTalk 8 to NetTalk 9

There are no known breaking changes that would affect NetTalk 8 applications. The only possible issue may be with methods that have changed prototype, so check the WebServer and WebHandler procedures for orphaned embeds.

AddLog

While not affecting the server directly, there have been some minor changes to the Log file format;
  1. The log-file name now uses leading zeros to pad the date and time parts of the name.
  2. The Prototype of the NetWebServer.AddLog method changed from
    AddLog PROCEDURE (NetWebServerWorker p_web)
    to
    AddLog PROCEDURE (NetWebServerWorkerBase p_web)
    Embed code in your WebServer procedure will likely be orphaned and will need to be moved to the new method.
  3. The Date and Time fields inside the log have been formatted with leading zeros to make parsing easier.
  4. A spurious comma after the <request> tag has been removed.

NetWebServiceMethods : API Updates

During the life of NetTalk 9 there have been some important updates to the Service Methods (NetWebServiceMethods). Because changes to the API impact client programs, it is important that you review this section and check any API's that you may have.

Note: As of writing this update, Build 9.17, it's highly recommended that if you are using xFiles and/or jFiles you update to be using jFiles 1.30 or later and xFiles 2.86 or later. There are important updates in both of these which affect the NetWebServiceMethods.

Version 9.17

Memo / Blob support

This build adds support for MEMOs and BLOBS to service methods. Support is automatic, but may impact services by adding fields which were not available before. As always, clients that ignore these fields will not be a problem.

Formatting Support

This build adds support for automatic formatting and deformatting of parameter and return fields.

This feature can be activated and deactivated globally. (It is on by default.)
It can be overridden at the field level in the Method.

Because this is a change, which is on by default, it will almost certainly change the output from your API. If you have custom clients using your API, you will either need to update those, or turn this feature in the method off. Please review your setup carefully to decide which approach to take.

Specifically all fields which are stored as "not String" and have a picture, are automatically converted to strings (using the picture) and vice-versa. Note that this applies to numeric fields which have a picture that formats the number with , separators. (eg 1,234.56). Your client program may not be able to accept numbers formatted in this way, so you may want to adjust the picture for these fields.

For Parameters this feature is limited to parameter types TABLE, DATE, TIME, NUMBER and STRING.  GROUP, QUEUE, STRINGTHEORY and FILE are not supported.

For Return values this feature is limited to FIELD (from the dictionary, not local data), TABLE and VIEW return types. For VIEWs only Generated View fields are done automatically.

Embed points exist for both XML and JSON which allow you to format, and deformat fields in hand-code.
Format Type Method Code Example
xml parameter xml.AssignField Self.CurrentField = Deformat(pString,'@d6')
json parameter json.DeformatValue Return Deformat(pValue,'@d6')
xml return value xml.SaveCurrentFieldToXML self.FormatCurrentField('@d6')
json return value json.FormatValue pLiteralType = json:string
Return clip(left(format(pValue,'@d6')))
For disconnected sync  the server, and the desktop need to be speaking the same language. For this reason the Desktop Sync client now defaults to auto formatting. If you disable auto formatting on the server side, then it needs to be disabled on the Desktop Client as well.

Currently the JavaScript sync is always formatted, so it is recommended that sync methods leave auto formatting on.

Field Prefixes

Field prefixes are a thorny problem for a couple of reasons. Firstly, they're a foreign concept in most languages, so they are often not desirable in a public API at all. Secondly they make use of a colon separator, which is not a valid character in a variable name in most languages.

For this reason you have the option to include, or exclude prefixes from parameters and return values. In most cases having the prefix OFF seems the better option.

For builds prior to 9.17 the default for prefixes was ON. For parameters and values added using 9.17 or later the default value is OFF. the setting for existing parameters and returns are not changed by the update, however support for the prefix support in the system has been overhauled so definitely check that your methods are still working the way you expect.

When writing a web app, colons are translated into a double underscore to make the names compatible with HTML. For ServiceMethods though, colons are translated into a single underscore. In builds 9.16 and earlier this was slightly inconsistent as simple GET and POST calls still made use of the double underscore, where XML and JSON used a single underscore. From 9.17 this has been made consistent so that all requests, and all responses use a single underscore if prefixes are ON.

XML Object START

Earlier builds did not reset the XML object back to native state between uses in the method. This is a problem when the same object is used for multiple parameters, or parameters and return values. Each use of the object is now prefixed with a call to the START method, which returns the object back to original state. If you have set properties for the procedure before the START call then those settings are now lost.

Popup Animations

See NetTalkWebBasic.htm#PopupAnimations

Host Variables

See NetTalkWebBasic.htm#HostVariables

Web Sockets

See NetTalkWebBasic.htm#WebSockets

IP Banning

See NetTalkWebBasic.htm#IPBanning
[End of this document]
Return to NetTalk Documentation Index