Email Report Nettalked

Introduction

Email Report Nettalked for Clarion 5-10... ABC/Legacy. This template allows you to email Clarion reports with the CapeSoft Nettalk template (not included!) in the user-friendliest way - right in the body of email messages. Besides this, you can also duplicate reports in RTF format to print from any email program and/or OS. It's the perfect tool for un-attendant and/or bulk emailing.  Plus it's compatible with ABC/Legacy Clarion Report, CPCS, RPM, DAS, Tintools  and Icetips report templates. 

Do whatever you want, but please don't move the cursor over the -> image! Download our 'Try before buy' shareware version of the template and test it right in your own application. You can have a quick look at emails generated by the template as well.

The Email Report Nettalked has very much the same functionality as its grandfather -
Email Report. The only difference is that it sends emails with the CapeSoft Nettalk template
rather than MS Outlook Express. It makes this template independent of any particular
email program. Besides, by default it works without preview so it allows developers
to easily implement un-attendant emailing as well as posting bulk emails.
It's important to stress that this template works in conjunction with CapeSoft NetTalk only.
So if you don't own the latter template, you won't be able to use EmailReport Nettalked!
Email Report Nettalked is compatible with Clarion, CPCS, RPM, DAS, Tintools, and Icetips
report templates. These report templates are directly supported.
In addition, the template has a special embed template that enables
it to be employed with a much wider range of report templates.
To ensure that your customers will be able to print/preview emailed reports with
any email program and/or Operating System, reports can be duplicated
as an attachment of RTF type. This file can be opened/printed even
with Windows WordPad program, so no 3rd party program is required.
Download RTF file generated by the template for a test.
You have the option of using the template just for saving your reports
in this universal RTF format. So later you can retrieve any archived
report, view, print and, if you have MS Word, email and even fax it!
Besides this, you can also define up and down navigation arrows with any GIF image
including animated ones. So you can make your emails as vivid as you like :-).
Optionally you can put a note right in the email body.
 
Advantages of using the template:
  • Emailing is fully automated so you can easily implement un-attendant emailing
    and thereby, for instance, automatically email reports to a number of clients each day.
  • Your program will be independent of any particular email program
    your clients may be using.
  • Reports can be saved to disc in RTF format. In this mode you will
    see just created RTF in default Windows RTF editor (MS Word or Windows
    NotePad 95-v.7) and will be able to save it anywhere and with any name you like.
    Optionally you can do it in silent mode.
  • Compatible with Clarion 5-10... ABC/Legacy
  • It doesn't make any changes to either Clarion native
    or 3rd party templates. It's taboo for us!
  • Compatible with all major 3rd party report templates: CPCS, RPM, DAS
    previewer, Tintools and Icetips previewer

  • As to the technical side, like all our templates Email Report Nettalked is a 
    white box template (no extra DLLs to ship)
  • You can allow your customers to decide whether to send reports
    in the email body or as RTF attachment or both

  • You can send and play audio files with your emails

  • Network friendly - can be run by many network users simultaneously

  • Works in multi-dll applications

  • To make your emails more attractive you can define up and down
    navigation arrows with any GIF picture, even animated (examples below).

New features

  • Landscape report support

  • No need to manually select both template chain
    and basic report template 

  • Direct support for Icetips previewer

  • Option to define email priorities (High, Low, Normal)

  • new internal help

  • True multi-dll support

  • Ability to attach files with wild cards: *.doc *.do? etc.

Installation
 
Run the installation wizard. It will guide you through a few simple steps. That is it.
IMPORTANT: If you are using Clarion 5-6, after selecting Clarion5-Clarion6 directory wizard
will offer to install it into C:\Clarion5(6)\Clarion8 or C:\C55\Clarion8 directory respectively.  
So don't forget to remove the last \Clarion8. But even if you do forget - no problem.
Simply uninstall the template and re-run the installation.
To start using the template you need to manually register it.
Here's how: Open Clarion (no application must be open). 
Go to menu Tools (Setup) -> (Edit) Template Registry -> Register
Select the new template ntemlrpt.tpl and then hit Open button.
You can find it in Clarion7(8,9,10...)\accessory\template\win
for Clarion >= 7 and in Clarion*\Template - for all others.
View our animated reminder on how to do this - Registering Template
(built with our JAVA Animated Help Builder).

Using the Template

   
Global Extension Template
Firstly, you need to install the global Email Report Nettalked extension template into the
application containing the report(s) you wish to email (no matter DLL it is or EXE)
In multi-dll application you'll need to insert this Extension into your main definition DLL
(which has all file, template, and ABC definitions) as well.
The template chain prompt is now deprecated so it is always disabled.
(Email Report Nettalked Template now does this automatically).
As an option you can define one email background colour here for all reports.
Later you can override it for any report you like (see picture below).
Email Report Nettalked supports global image shrinking. But you have the option
to override it locally for each report. You can use either numbers or your variables here.
We've added this shrinking feature for developers who wish to
print emails or send landscape reports. 
The rule of thumb - the more you shrink image the worse
the quality of the image, so use this option with care. But in some cases it'll
help you to print emails more economically or to fit wide reports into the email body.
You can try changing report fonts. Bold font always gives a much better
performance. And shrinking has hardly any influence on the
quality of printed emails.
You have to bear in mind that RTF uses the same shrinking factor as 
the image in the email body.
There is a new setting which you'll not find in any of our other email templates -
Define email setting variables globally. It goes without saying that if this checkbox
is checked - all email settings will have global scope, or if not, then local.
The last 2 prompts are optional. These are internal RTF document properties.
So your customers won't see them. Nevertheless, you can leave
your "signature"  here if you wish.
By default the template creates subdirectory \VH\ under your working directory
to keep temporary template files. On some networks this may cause problems.
So the last prompt is where you can override this default behaviour.
The template creates a global variable associated with this prompt GLO:WorkingDir
So you can specify any other directory thus: GLO:WorkingDir = 'C:\Temp'
In this case the template will use C:\Temp on each workstation to build all required files. 
Even if this directory doesn't exist, the template will create it.
It will even create nested directories for you! So if you prime this
variable to say C:\Temp\A\B\C you will find this directory structure.
And if you don't use this variable the template will work as always, that is
it will create a working directory \VH\ on the server under your working 
directory and use that.
Normally Keep report pages checkbox should be OFF. When ticked it will
save all temporary WMF report pages in the working directory.
You may need it when using non-standard reports to estimate
those picture sizes. Don't forget to set it to OFF before program release.
Though even if you do, it won't cause issues for your end-users.
The only difference is that their working directory will be slightly larger.
For more info please hit the question marked help buttons
To make NetTalk happy, you have to include global NetTalk extension -
Activate NetTalk - here as well.
 
Procedure Extension Template
First of all, each report will need both EmailReport Nettalked and the CapeSoft
Include NetTalk Object procedure extensions.
Base class for the latter is Net Email Send. NetTalk defaults to
Object Name ThisNetSomething.
If you change it, don't forget to change the respective prompt in the Email Report
Nettalked (picture below, general tab). Apart from that there are no
restrictions on using the NetTalk email engine. So you can use it as though there
was no EmailReport Nettalked template.
The picture below illustrates the settings you need to define in the report extension.
To open a Tab other than first one just move the cursor over it.
 
General Tab
Report behaviour depends on one global variable only - NERG:Mode
You can use either numbers or pre-defined equates. We've placed them on the last tab
so you can copy and paste them into your code from there:

0 - NERQ:Print         !Print as ordinary report
1 - NERQ:InBodyRTF !Email in Body and RTF
2 - NERQ:InBody      !Email in Body only 
3 - NERQ:InRTF       !Email in RTF only
4 - NERQ:Save        !Preview RTF (and save manually) 
5 - NERQ:SilentSave !Save silently

So it functions as an EmailReport Nettalked Global Request. In other words, if you say:
NERG:Mode = NERQ:EmailInBody; YourReport() - reports will be emailed
in email body etc.
Here you have to select your Basic Report template from the combo.
You can find it - on the bottom of the first tab - General.
(see picture below):
 

It defaults to whatever report template it can see in the current report procedure.
It's important to stress that this is just a suggestion. So if you wish to,
you can reselect any other report template. You may want to do this only in exceptional 
situations. For instance when you want to apply an embed template to solve an unusual 
requests of end-users (email and print at the same time etc.). Or you have some uncommon
hybrid say CPCS + RPM. We provide examples for each of these directly supported templates 
in Clarion*\Examples\NtEmlRpt directory so you can investigate recommended
template settings there.
IMPORTANT: If you want to try to use this template with any report template
other than those directly supported (Clarion, CPCS, RPM, DAS, Tintools, and Icetips),
we'd strongly recommended that you download the free shareware version
of the template to ensure it will work. You have to selects Other from the Basic
report template prompt and use the embed template. You should also do this if you
want to use this embed in one of the supported report templates.
It can help you to satisfy any unusual needs of your clients. Email and
print report at the same time, for instance.
In the template examples you can see how this embed can be used.
 
Report Tab
You can specify the name of the RTF attachment file either from a variable or
by hard-coding it from the prompt as well (using say 'ReportCopy' will create
attachment ReportCopy.rtf). If you use a variable just inset its name
or find it via the lookup button. No exclamation marks are required!
You have to bear in mind that RTF uses the same shrinking factor as the
image in the email body.
You can define the image shrinking factor applicable for both body and RTF reports
and specify variable names for RTF file name and path for saving reports.
The rule of thumb - the more you shrink an image the worse
the image quality, so use this option with care. But in some cases it'll
help you print emails more economically or fit wide reports into the email body.
You can try changing report fonts. Bold font always gives a much better
performance. And shrinking has hardly any influence on the
quality of printed emails.
Starting from version 6 you have full control of report sizing (both in Body and RTF).
By default the template supports A4 reports. So the only thing you need
do is to specify whether the report has Landscape layout.
To define report margins (for RTF) and report width and height the template generates and 
uses 4 global variables: NERG:RTFleft, NERG:RTFtop, NERG:RTFwidth, and NERG:RTFheight.
These values should be specified in 1/1000th of an Inch (Clarion default units).
The simplest way to estimate your report sizes is to collect WMFs by setting
global Keep report pages checkbox ON. Then open any of WMFs with Windows
MS Paint and from Image -> Attributes menu find out the sizes in Inches.
Remember to multiply it by 1000. This need only
be done if you use non-standard report sizing. You will know 
immediately because non-standard sizing dramatically decreases report quality.
So if you notice this you'll need to check report sizes:
Otherwise you can completely ignore Position Group.
The type of prompt used for all 4 size variables
allows you to define them either with a variable or implicitly as a number.
So you can use predefined variables. You can 
define and use your own variables. At last you can simply
place a margin value right into the corresponding prompt. As long as you follow
standard Clarion syntax you won't have any compile errors.
Optionally you can define images to use for navigation up and down arrows.
We ship a number of arrow GIFs with template:
Of course you are free to use any others.
IT'S VERY IMPORTANT to remember that those images should be available at runtime.
So you need to ship them with your application either in the working directory or in a 
subdirectory of your working directory (where the main EXE is).
 
Email Tab
This tab has a list of variables required by the NetTalk template to send emails.
It's your responsibility to prime them properly before calling a report.
For more details see our example application.
With the button at the bottom you can open a list of variables which you may only rarely use.
Both compulsory and optional prompts accept any valid Clarion strings. Use lookup
buttons to find and append any field from your Application as you would for formulae.
 
Body Tab
Optionally you can define a heading comment here. Just follow plain
Clarion syntax and build any letter you like. This option may be especially useful
when sending reports as RTF attachments only. So you could explain here what to do
with any attachment.
Everything you add here goes directly into the embedded email HTML file.
So you can use HTML tags as well. (Tag usually starts with something
like <font> and ends with </font>. It can be <img> and </img> etc.)
Just remember that each tag should occupy one line in the body queue.
This restriction comes from the way we build the message body, not from HTML syntax.
To make life easier we've put new-line tag after each line of HTML
So if you try to split a tag on more than one line - this tag will get broken
by the new-line tag inserted by template.
And finally, one more thing to bear in mind - the template stores this note in NERQ:BodyQue
global queue. So for extra flexibility you can completely ignore Body Note template Tab
and populate this queue directly from the special embed: EmailReport - After filing queues.
So just use the usual queue handling:

FREE(NERQ:BodyQue)
NBQ:Line = 'Line No 1'
ADD(NERQ:BodyQue)
NBQ:Line = 'Line No 2'
ADD(NERQ:BodyQue)
NBQ:Line = 'Line No 3'
ADD(NERQ:BodyQue)

If you omit FREE() function call, the template will append those lines to
whatever you've already specified in the Body Note template prompt.
If you can also play audio files in your emails. You'll need to specify
a Sound file and how many times you want it to be played.
Like the arrow image files those sound files must be available at runtime. So you
need to ship them with your application.
From our experience not all users appreciate this feature. So it's advisable
to show them such 'talking' emails first :-)
 
Attachments Tab
Email Report Nettalked takes care of Reports in RTF attachment. So
this attachment prompt allows you to specify a list of any other files
to be sent with your emails.
Both attachments and email body lines are stored in 2 global queues (NERQ:AttachmentQue
and NERQ:BodyQue respectively). So for all emails you can just use the template settings
that will populate those queues for you. But if you don't want to bother - you
can directly populate those queues from an embed point we created for you -
EmailReport Nettalked - After filling Body/Attachment queues. 
Like the email body note, these attachments are stored in a global queue (NERQ:AttachmentQue)
So for all emails you can use either template settings or populate this queue directly
from the same embed point. You can also combine these 2 methods.
For instance:

NAQ:FileName = 'C\Temp\Note.doc'
ADD(NERQ:AttachmentQue)
NAQ:FileName = 'C\Windows\help.doc'
ADD(NERQ:AttachmentQue)
...

See example for details.
Equates Tab
This is a place where you can copy predefined equates for pasting them 
into your code. It's not used by the template at all. So you can store anything
you wish to here.
 
We've installed examples into your Clarion (Clarion5 or C55) Examples/NtEmlRpt
directory. Or Clarion7(8,9,10...)\Lessons\NtEmlRpt in Clarion 7-10....
So for various settings you can investigate the source.
If you only have C55  installed you'll need to recompile Demo to run :-(
IMPORTANT: In email mode report cannot go without preview, so
you should always keep the Print Preview checkbox ON no matter which
basic report template you are using. 
Control template
By default the Email Report Nettalked template sends emails silently without preview.
For those who may build their own email preview this control template
can save time. You can find a few examples in our demo application.
Conversion from previous versions
If you use CPCS basic report template or Other,
you'll have to reselect it from the basic report template combo on
the General Tab: newcomer - Icetips template - needs space.
We apologize for any inconvenience these changes may cause.
TIPS (you are welcome to send your own tips to this area!)
1. To compile our application from C55\Examples\EmlRptNt\Demo subdirectory,
    you need all 3rd party Report templates (CPCS, RPM etc.) If you don't have them
    you can find versions of these applications without any 3rd party templates
    in other subdirectories: \Clarion, \CPCS etc.
2. Only if you use 5.5F or C5.5G Legacy, you have to fix a Soft Velocity bug
    which interferes with a number of 3rd party Legacy templates. Basically you have to:
    search your CW.TPL file for the following line:

     #SET(%CWTemplateVersion,'v5.5')
     and replace it with these lines:
     #! #SET(%CWTemplateVersion,'v5.5')
     #SET(%CWTemplateVersion,'v2.003')

     If you can't find the above line then look for the following line....

     #EQUATE(%CWTemplateVersion,'v5.5')
     and replace it with the following.....

     #! #EQUATE(%CWTemplateVersion,'v5.5')
     #EQUATE(%CWTemplateVersion,'v2.003')

    
Read more: http://www.thetingroup.com/news.htm
3. To get help quickly you can hit any of the question-marked buttons
    (picture below). It's a new type of template help we've recently developed,
    so please let us know what you think of our new help
Move cursor on top of a Tab to open!

Copyright (C) 2015 Vivid Help Systems Pty Ltd