Vivid Help Systems Pty Ltd - Clarion EmailReport Nettalked Template

Email Report Nettalked 7.7

Introduction

Installation

Usage

Conversion

Introduction

EmailReport Nettalked Template for Clarions after 8 is now using *.PNG images instead of Aldus *.WMF that makes it universally compatible with all devices (not just MS ones as before) and allows you to send Clarion reports in the user-friendliest way - right in the body of email messages. It emails Clarion reports with the CapeSoft Nettalk > 10 (not included!). 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:

Template generated emails can be viewed on any device.
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 other than 11, after selecting Clarion9-Clarion10 directory

wizard will offer to install it into C:\Program Files (x86)\SoftVelocity\Clarion9\Clarion11

or C:\Clarion10\Clarion11 etc. directory respectively.

So don't forget to remove the last \Clarion11. But even if you do forget - no problem.

Just uninstall the template and re-run the installation.

To start using the template you'll 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 new template emailrpt.tpl and then hit Open button.

You can find it in Clarion9(10...)\accessory\template\win

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.

The last but not least, there is a new text box at the bottom where you can

optionally put any code to prime/override any Nettalk email setting in all reports.

Say, if you put there: ThisNetSomething.Subject ='Email Subject'

all emails will have Subject 'Email Subject'

Needless to say that it will only work if you use the same Nettalk object name.

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.

Shipping

Unlike previous versions this one needs native ClaRunExt.dll

that in turn requires .Net 3.5 or higher is installed on target machines.

Please keep in mind that unlike other run-time DLLs Clarion doesn't copy it

so you have to copy it manually from Clarion*\Bin\ directory.

If you see empty emails, make sure you have your Clarion's

ClaRunExt.dll in working directory.

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!