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]