NetTalk Upgrade to NetTalk 12
Introduction
This document works through the major changes between
NetTalk 11 and NetTalk 12. It is designed for users, currently experienced
with NetTalk 11 to quickly identify and use the new features in NetTalk
12. 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.
I've upgraded to NetTalk 12 (or later) and
I'm getting Compile Errors!
NetTalk 12 (all levels) requires
jFiles. Make sure the jFiles global extension is
added to your application. If this is a Multi-DLL system then set the
Multi-DLL tab, on the jFiles Global Extension, appropriately.
The next most common cause for compile errors (in NetTalk class code, or
generated code) is because one of the other related tools you are using
has not been updated. Especially
StringTheory and
xFiles.
If you are getting compile errors in your embed code then see the list
below for the various changes.
Using NetTalk 12 (or later) with Clarion 8, 9
or 9.1.
Invalid Use of Private Data
Clarion 8 and 9 do not provide access to the
FileManager.HasAutoInc property. This means you'll get an Invalid Use of
Private Data error when compiling, on a line that looks like this;
If p_forceWrite and RM.Me.HasAutoInc = false
!8000
RM.Me.TryInsert()
End
To correct this open your \clarion\libsrc\win\abfile.inc
file.
Search for the line;
HasAutoInc
BYTE,PROTECTED ! Auto-increment or not flag
and comment out the ,PROTECTED part - leaving
HasAutoInc
BYTE ! ,PROTECTED ! Auto-increment or not flag
New Features
The goal of this section is a quick overview of things
that have changed since NetTalk 11 which experienced NetTalk 11 users will
want to know about.
NOTE: NetTalk uses many of the latest
methods and functions in the following products. If you are using these
then please update them at the same time.
StringTheory 3,
xFiles,
jFiles 2,
WinEvent 5,
Draw 4,
File Explorer 5,
Chrome Explorer
New Requirements
All levels of NetTalk now
require
jFiles 2 (it is no longer optional in Desktop and Server, it
was previously required for Apps.)
[1]
Secwin 6 is no longer supported.
Secwin 7 IS supported.
Supported Browsers
All modern browsers are supported, including Edge,
Chrome, Firefox, Safari, iOS Safari, Android Browser and Chrome for
Android.
Support for IE is limited, and IE is not targeted as a supported
browser. Most features will likely work under IE, however not all of
them will. Layout, and CSS issues on IE are likely to be common.
TLS Levels
In NetTalk 12 all clients, and servers, that make
use of TLS connections require
at least TLS 1.2. By
default TLS 1.0 and 1.1 are not supported by your program. This applies
to all TLS connections, Web Server, Web Client, Email, FTP and so on.
If you need to support an older, less secure, version of TLS because you
are communicating with an old server, or old client, then you can set
the SSLMethod property to
NET:SSLMethodTLS.
For example;
Net.SSLMethod = NET:SSLMethodTLS
For more information on possible TLS Level settings see
Levels.
Desktop
Quicklist
- NetOAuth
and NetDrive examples now available as FileExplorer or ChromeExplorer or External Browser versions.
- NetOAuth
support for PKCE flow added.
- NetOAuth
support for External Browser (same machine) and External
Browser (remote machine). (Re import of OAuthLogin window
required)
Web Server
Quicklist
- New Theme framework
- New Documentation - Themes
- Old themes should still work
- New Themer (86) example
- New theme "PalmTree"
- Icon framework changed to SVG instead of PNG.
- Support for FontAwesome
added.
- Form
- BLOBs are now supported as a valid source for Text fields on
Forms.
- New Tab Style for Forms - TaskPanel - Similar to Accordion (or
rounded) but panels can be open or closed independently.
- Add: Tab Headers on Carousel tabs
- Add Tab Headers / (Clickable) Breadcrumbs on Wizard Tabs
- Add: Icon support for Tab Headers (Carousel, Wizard, Rounded,
Plain)
- Change: Color-Lookup form field now uses standard lookup
button, and has been generally restyled.
- New Editors
for Text Fields: Advanced Code Editor (ACE) and
CKEditor 4.
- Add: Form-Fields on Memory forms, with Initial values (on data
pad) are primed
- WebSocket support added for field types; Checkbox, Color,
Date, Drop, Email, Hidden, Month, Number, Radio, Range, Slider,
Spinner, String, Time, Telephone, URL, Week
- Live web socket updates on a form are visually highlighted
with an animation
- New Layout method option "Div Grid" added to existing "Div
Flex" and "Table"
- Browse
- Added EIP field types; Color, Week, Month
- New Layout method option "Div Grid" added to existing "Div
Flex" and "Table"
- Menu
- Set "Hamburger" Icon
- Set Icons for menus and menu items
- Popups
- Global Header-Back-Button options, with local overrides.
- New Client-side
Session Manager widget for footer procedure, and template
options.
- Added template support for Session
Tables storing additional Session information.
(NetWebHandler, Actions, Session Tables list)
- Add: NotifyChangeSession method
- Change: Footer floats to the bottom of the viewing area when the
page is smaller than the viewing area. Footer height must be set
in PageFooterTag procedure
- New default global class names added to all the Button Sets.
- Support for Secwin 7 added, Support for Secwin 6 dropped.
- Added command URL /freecache
to clear the server-side cache.
- p_web.REDIRECT commands now use 302 (temp redirect) instead of
301 (perm redirect) by default.
- REDIRECT commands support cookies, and by default cookies set
with ADDCOOKIE are sent with a redirect.
- Added support for passwords on .KEY files (TLS Certificates.)
User-interface to this option coming in a future build.
- Added Websocket support to MultiSite Host Example (you need to
turn on WebSocket script to support this in the app)
Behind the scenes
- When building complex div names, the separator between
procedures has changed from an underscore (_) to a hyphen (-)
- CARoot.Pem updated
- OpenSSL updated to version 1.1.1i (1.1.1.9)
- jQuery updated from 3.4.1 to 3.5.1
(deferred for now)
- Slick.js (Carousel widget) updated to resize when unhidden.
- multi-line-Browses have classes for first-row, middle-row and
last-row added.
- Session data information moved from WebServer class to
NetSessionsQueue class. Uses an interface to make replacing the
Session mechanism easier.
- Loading and Saving of session states moved out of WebServer
procedure into NetSessionsQueue class.
- Added WebHandler Authenticate(token) and CookieAuthentication
methods.
- Added Send(json), SendJson(Json) methods
- Security templates overhauled to make it easier to plugin
various security engines. (like Secwin 7).
- Added methods SessionLevelOk, RestrictOk, CanCall,
CanCallAddSec, StyleWidth
- Removed: Template settings "only serve if secure".
- New property p_web.site.ConnectionSecure. Is set to true if
either p_web.SSL OR p_web.site.ExternalHTTPS is true. Treat this
property as read-only.
- NetMD5 function has been deprecated - use NetMakeHash instead.
- Close errors for WebServer and Webclient objects have been
suppressed.
- Some improvements to the wizard.
Apps
Quicklist
- CustomJson and SetJsonProperties methods in NetWebSyncClient
class now take a JsonClass parameter, and the self.json parameter
has been dropped. Check for orphaned embed code in your NetSync
procedure in Disconnected Desktop Apps. In your embed code use the
parameter (pJson) in place of self.json.
Changes Required to Convert your App from
NetTalk 11 to NetTalk 12
Notes
Note 1: NetTalk 12 require jFiles: Why now?
For the most part we like to keep additional
accessories as "optional" - they only become required when they are in
some functionality that the developer is using. For example, jFiles is
used internally by the NetSync class, and so is required at the App
level if any Sync features are being used.
However making accessories optional has three effects, one minor, and
two major.
The minor effect is that all the code which uses (say) jFiles has to be
wrapped in a conditional compile. This is tedious, and can lead to minor
build issues, but it's not a big deal, and can be effectively managed
from here.
The second issue is more critical - because the template is optional
it's possible for the developer to forget to include jFiles in an
application, where an object that uses it is being used (NetMaps for
example). This will lead to some functionality in the class being
"broken" and can lead to support questions and developer frustration.
It's easily resolved but usually requires a round-trip support question
and a day's delay. Related to this the NetTalk template cannot warn of
necessary jFiles updates or things like that.
The third issue is the most complex, and hardest to debug. When a
product is optional then it is effectively not usable as a parameter to
a method. While technically it's possible to use optional products as
parameters it requires that in multi-dll situations either all apps have
the template, or none do. As can be expected this is hard to verify,
which in turn means mistakes happen, which leads to really strange
behavior in the app, which in turn is very difficult (and unintuitive)
to debug. Given the risk, wherever possible, using optional classes in
parameter lists is discouraged.
jFiles has of course been useful, and is a requirement of numerous
classes. This requirement is only growing as more and more services and
HTML widgets use JSON as their primary means of communication. It would
appear this trend will continue, and is increasing in speed. Making
jFiles a requirement not only makes integrating these services easier,
it also opens the door to additional features in NetTalk improving
performance in the future.
Note 2: NetTalk 12 Alpha/Beta program
The NetTalk 12 release is a little different to the
previous NetTalk major-version releases.
With previous releases, the first build is a substantial update with
many new features, and (as much as possible) all the potentially
breaking-changes. Thus once on say 11.00, moving up through the 11.xx
versions becomes usually nothing more than recompiling.
The release of Secwin 7 - and specifically the need to separate Secwin 6
and Secwin 7 support - means that the NetTalk 12 build is being released
a lot earlier in the cycle than is expected.
This means that it is expected that additional breaking-changes will be
introduced during the alpha/beta cycle. So when upgrading during the
beta cycle please pay particular attention to the Release History, and
this document, for required changes.
[End of this document]
