NetTalk Upgrade to NetTalk 8
Note:
NetTalk Web Services requires xFiles version 2.86 or later
Introduction
This document works through the major changes between
NetTalk 7and NetTalk 8. It is designed for users, currently experienced
with NetTalk 7 to quickly identify and use the new features in NetTalk 8.
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 7 which experienced NetTalk 7 users will
want to know about. Since there are a few changes in NetTalk 8 which
invalidate things that were true in NetTalk 7, and unlearning previously
sound information and habits is hard, please pay particular attention to
this section.
Clarion 5.5, 6 and 7 are no longer supported.
NetTalk 8 requires Clarion 8 or later.
PACKET and LOC:OPTIONS have changed, PacketLen removed
Some p_Web Method names have been tweaked
Check for Orphaned Embeds in the WebHandler
procedure
Changes Required to Convert your App from
NetTalk 7 to NetTalk 8
All New Packet variable
The local variable called
PACKET
is now a StringTheory object, not a String. If you have set, or
added to the Packet variable in your embed code, then that code will
need to be slightly altered.
replace
packet = clip(packet) & 'whatever'
with
packet.append('whatever')
replace
packet = whatever
with
packet.SetValue('whatever')
While the first construction will result in an error (
Cannot
call procedure as function) the second construction above (
packet = something) will not. In order to
identify the places in your code where you may have this construction,
you should
- Go to the Application Global Extensions,
to the Activate NetTalk Web Server
extension, Advanced tab and set the Packet Variable Name to something other than
packet, like for example, pkt
- Compile the application. Only hand-code use of the Packet
variable should result in errors. Replace the hand-code
with the correct code as described above (using the new name you set
in step 1.)
- When the app compiles cleanly then it is recommended (although not
mandatory) that you go back to step 1, reset the variable name to Packet, and recompile again. On this pass
through change pkt back to packet.
This step is not strictly necessary, but will make supporting the
app in the longer term much easier. We recommend taking a few
minutes to do this.
The PacketLen variable has been deprecated
the PacketLen variable
(generated by the templates) is no longer used, and has been removed.
You can get the length of the packet, if necessary using packet.Length()
All New Loc:options variable
The local variable
loc:options
is now a
StringTheory object, not a
String. This means that if you have used this
variable in your hand code, then your hand-code will need to change
slightly. The biggest difference is that the
SetOption
method no longer returns the string. For example;
loc:options =
p_web.SetOption(loc:options,'setting','value')
becomes
p_web.SetOption(loc:options,'setting','value')
While the first construction will result in an error (
Cannot
call procedure as function) the second construction above (
loc:options = something) will not. In order to
identify the places in your code where you may have this construction,
you should
- Go to the Application Global Extensions,
to the Activate NetTalk Web Server
extension, Advanced tab and set the Options Variable Name to something other than
loc:options, like for example, jOptions
- Compile the application. Only hand-code use of the loc:options
variable should result in errors. Replace the hand-code
with the correct code as described above (using the new name you set
in step 1.)
- When the app compiles cleanly then it is recommended (although not
mandatory) that you go back to step 1, reset the variable name to loc:options, and recompile again. On this
pass through change jOptions
back to loc:options. This step
is not strictly necessary, but will make supporting the app in the
longer term much easier. We recommend taking a few minutes to do
this.
Web Server Log List Format Updated
More fields have been added to the LogQueue in the
WebServer, so you need to do one of the following;
- Delete the Log Control Template, and add it back again OR
- Use the Format-List functionality in the Window Editor to map the
columns to the items in the LogQueue structure OR
- Use the Window Source Editor, to replace the FORMAT() property of
the LIST control to
FORMAT('51L(2)|M~IP
Address~@s30@28L(2)|M~Socket~@n7@28L(2)|M~Thread~@n3@51L(2)|M~Date~@D17B@36L(2)|M~Time~@T4B@1020L(2)|M~Description~@s255@')
_NoColon method renamed to NoColon
If you have used p_web._nocolon
in your hand-code then replace it with p_web.NoColon.
Check the WebHandler procedure for orphaned embeds.
File Methods have been renamed
The file methods _OpenFile,
_CloseFile, _AddFile,
_PrimeFile, _GetFile,
_UpdateFile and
_DeleteFile have been renamed to OpenFile,
CloseFile, AddFile,
PrimeFile, GetFile,
UpdateFile and
DeleteFile respectivly.
If you have used these in your hand-code then remove the leading _. Check the WebHandler procedure
for orphaned embeds.
Note that it is perfectly ok for you to use normal ABC file handling
methods in your own hand-code. The file methods are included in the
class to cater for non-ABC programs. there is a slight performance gain
when using the ABC file methods over the p_web methods.
SetProgress Method has changed
The
SetProgress method
now takes three parameters instead of two. If you have called
SetProgress
in your own code (as described in the
Report
documentation) then you will need to review that code to use the
extra parameter. If you have used it in your code, then the compiler
will generate an error
No Matching Prototype Available
Web Client
Structure Changes
Net:simpleSSLCertificateOptionsType
- CARootFile, CertificateFile and PrivateKeyFile fields extended
to bigger strings.
- ServerName property Added
Net:SimplePacketType
- SharedMemory property added
- _Reserved property size reduced
Security
Equates for TLS1.1 and TLS1.2 added as possibilities
for
SSLMethod property.
Equate for all TLS (1.0, 1.1 and 1.2) added.
Equate for SSLv3, TLS 1.0, TLS1.1 and TLS 1.2 added.
Performance
Although unglamorous, a number of performance
enhancements have been made. The following list contains some of the more
important ones;
Shared Ram for Static File Downloads
RAM is one of the biggest constraints of the web
server. A 32 bit program can only access, at most, 3 Gigs of memory. In
NetTalk 7 static files are loaded into RAM before they are sent to the
browser. In NetTalk 8 these memory blocks are shared, meaning that if
the server is busy sending a (large) file to one browser, and another
user requests the same file, then the second request can share the same
file-in-memory as the first request.
Support for keep-alive
Support for the Keep-alive header has been added.
This allows a connection between the browser and the server to be kept
open for a small period of time after a request is made (and replied
to.) This allows the browser to make another request, across the same
connection if desired, which in turn is faster because it does not have
to negotiate a new connection. This improvement is most applicable to
SSL connections where the connection setup can take a bit of time.
Auto-Cache
NetTalk now caches small static files up to a
maximum cache size. This improves delivery of common small static files,
such as CSS, JS and Image files. You can adjust the size of the cache,
and the maximum size of files being cached on the new WebServer
Performance tab.
Various Code Optimizations
Web Services
Note: NetTalk Web
Services requires xFiles version 2.86 or later
NetTalk 8 contains new templates for creating Web Services. That is
discussed
here.
Form
Maps
A new Form Field type called "Map" has been added.
Maps consist of a base layer (for example a map or satellite image)
provided by a Provider, combined with data from your database. Data can
be expressed as "Markers" on the map, or it can be expressed as an
"Area" on the map. A single map can contain multiple data sources.
You can read more about the Maps feature
here.
YouTube
A new Form Field Type called "YouTube" has been
added. This allows you to embed a YouTube video inside your application.
All the Google options for an embedded video are exposed via the
template interface.
The settings for the YouTube control are documented
here.
Webcam
A new Form Field Type called "Webcam" has been
added. This allows you to access the Webcam on the client machine (if
the user gives you permission to do so.) This field uses the
GetUserMedia API which is currently not available in
some
browsers.
The settings for the Webcam control are documented
here.
External
A new Form Field Type called "External" has been
added. This allows you to fetch data from a second server (called an
Agent) and include that data on a web form.
The settings for the External control are documented
here.
Procedure
Up to NetTalk 7 the Procedure form field type did
not allow a Form to be embedded on a form. NetTalk 8 removes this
restriction for a specific case.
A new template option
Generate
<FORM> tag has been added to MEMORY forms. If this is OFF
then no
<form> and
</form>
HTML tags will be generated, thus allowing this form to become
includable on a parent form.
Start Button
Progress Bar
- Template
option to set the width of the progress bar.
- Client-Side resets for Progress bar - fields are refreshed when
progress completes.
Browse
Export Button
Use of this feature
requires
xFiles version 2.86 or later. For more on xFiles see the
CapeSoft Web Site.
An Export button has been added to browses. When this is clicked the
server will create an Excel spreadsheet (as xml), based on the browse,
and send it to the user. They can then open the file in Excel, save it
locally and so on.
The button is declared globally (WebServer / Buttons) and can be
activated or deactivated globally (WebServer / Defaults). You can
include, or exclude the button locally as well.
Other
- Locator Type option on sort tab for browse fields. Allows you to
specify a locator type for a specific column.
Wizard Changes
- The Wizard(s) now let you generate a WebService and
WebServiceMethods for the (selected) tables in your dictionary.
- Support for xFiles (required by web services and Export
button) and OddJob (required for serving PHP pages) global
extensions added to the wizard.
NetWebPage Changes
- Include Standard Header, and Include Standard Footer options added
to NetWebPages.
Reports
Using the Media control, and the new Progress Bar and
Start button functionality, it is possible to include generated reports
directly onto a form. The Example
PDFReportRequiresEE
(13) has been updated to reflect these new options. The
Reports
Documentation has also been updated to document how it is done.
Global WebServer Extension
Advanced Tab
- As mentioned above, you can set the name of the PACKET variable on
the WebServer Global Extension. This is very useful to do to
identify the use of PACKET in hand code (which may now be
incorrect).
- New option on the Advanced tab to set the Maximum
Threads limit.
Settings Moved
- Default HTML Editor : Now on Defaults / Form
- Theme : Now on Defaults / General
WebServer Procedure
Advanced Tab
- Combine Common Files, Serve Pre-compressed Files, Compress Static
Files, Compress Dynamic Files and Auto-Check Cached Files have all
been changed to an Expression instead of a checkbox. This allows
these settings to be set at runtime using an INI field, or Settings
field or whatever.
Garbage Collection
Files in the \web\reports folder which are dated
before yesterday, are automatically deleted.
Updated Scripts
External JavaScript Updates
- jQuery - version 1.11.0
- jQuery-UI - version 1.10.4
- Modernizr - version 2.7.1
- jQuery File Upload Plugin - 5.40.1
- jQuery.SignaturePad - 2.5.0
- AD Gallery - 1.2.7
- Redactor - 9.2
- Tiny MCE 4.0.19
New p_web Properties and Methods
Properties
Property |
Description |
ShortSOAPAction (String) |
contents of the SOAPAction header field, but with the Host
name (if it exists) removed. |
SOAPAction (String) |
contents of the SOAPAction header field |
ServiceErrorQueue (&ServiceErrorQueueType) |
A queue which is populated with errors when a service method
has been called. |
WSDL (&NetWSDL) |
Pointer to a NetWSDL Class. Used when generating WSDL files. |
xml (Long) |
Set to 1 (and p_web.GetValue('xml') is primed, if the incoming
request has a content-type of text/xml or application/soap+xml |
|
|
Methods
Method |
Description |
AddServiceError |
Adds an entry to the ServiceErrorQueue |
ClarionTimePicture (pic) |
Takes a Clarion time picture and returns an example string of
that picture (like hh:mm) |
CreateMapDiv |
|
CreateYouTube |
|
GetBrowseHash |
|
GetLatLng |
|
SetMapZoom |
|
SetMapDevIdOptions |
|
WrapOptions |
|
Methods refactored to use StringTheory thus removing string length
limitations: CreateHyperLink, CreateSelect, CreateMedia, CreateInput,
CreateRadio, CreateTextArea
Examples
PDFReportRequiresEE (13)
Using the Media control, and the new Progress Bar
and Start button functionality, it is possible to include generated
reports directly onto a form. The Example
PDFReportRequiresEE
(13) has been updated to reflect these new options. The
Reports
Documentation has also been updated to document how it is done.
Media (74)
The Media (74) example has been updated to include
YouTube videos on a Form, and as a child of a Browse.
Maps (76)
A new example, Maps (76) has been added. This shows
the use of the MAP form field in various places in the application.
WebService (77)
A new example WebService (77) has been added. This
contains several services, and multiple methods which acts as a
demonstrator of several common WebService techniques. This example
requires xFiles version 2.86 or later.
ExportRequiresXFiles (78)
A new example ExportRequiresXFiles (78) has been
added. This requires
xFiles, and demonstrates the ability to export a
browse to an Excel spreadsheet.
Webcam (79)
A new example Webcam (79) has been added. This
demonstrates the ability to use a webcam to take a photo of the user on
a NetWebForm.
ExternalServer (80)
A new example ExternalServer (80) has been added.
This demonstrates reading data from a second web server (called an
AGENT) to provide information to the form. In this case the agent
program reads in strings in a COM port (using WinEvent) and provides
that to the web page. This has the effect of allowing local hardware
(such as a barcode or prox-tag reader) to be attached to the client
computer, and for the web page to access the information coming from
that hardware.
The example is in two parts, the normal web80.app program, and an
agent.app program that runs on the client machines, and accesses the
client hardware. Note the settings tab on this app which allows you to
set the COM port being read, and also the port number to run the agent
on.
[End of this document]