Vivid Help Systems Pty Ltd - Clarion EmailReport Template



EmailReport Template Legacy 6.12


Introduction Installation Usage Conversion

Introduction

EmailReport for Clarion 5~5.5~6.3 Legacy Template allows you to send Clarion reports in the user-friendliest way - right in the body of email message. Compatible with Legacy Clarion Report, CPCS, RPM, DAS, Tintools, and Icetips report templates. You can duplicate report in RTF format to print it from any email program and/or OS or send RTF only. Besides you can use template just for saving report to disc in this universal format. No email settings are required from end-users. The picture on the right side gives some idea how template works. Do whatever you want, but please do not hit the arrow!!! Download 'Try before buy' free version of template and test it right in your application. You can have a quick look at emails generated by template as well.

Unlike all other templates the EmailReport sends Clarion reports right in the body
of email message, rather than an attachment of some kind.
It makes this report immediately available for email addressee. There is no need for him/her
to look for proper version of MS Word to open attached *.DOC. Nor should he/she download
and install Acrobat reader (9MB or so) to view *.PDF file attached.
This template is designed to work in conjunction with Outlook Express
which these days is a part of Windows OS. So everybody who is using Windows has it.
Users still can employ any emailing program they like for their ordinary emailing,
but for sending Clarion reports EmailReport template will automatically invoke Outlook Express.
And if they are really kin on having those sent emails in another email program, they can
from time to time import them from Outlook Express.
EmailReport is compatible with *Clarion,* *CPCS, RPM, DAS, Tintools, and* *Icetips* report
templates. Reportedly it works with Fomin report builder as well (in Clarion Report mode).
Besides now, with a new embed template EmailReport can be used with
much wider range of report templates.
To ensure that your customers will be able to print/preview emailed report with
any email program and/or Operating System, report can be duplicated
as attachment of RTF type. This file can be opened/printed even
with Windows WordPad (95-XP) program, so no 3d party program is required.
Not to mention MS Word (95-XP) that, if installed, will do the job.
Download generated by template RTF file for testing.
As a matter of fact EmailReport *is much more than just report emailer.*
*You have an option to use template just for saving your reports*
in this universal RTF format. So later you can retrieve any of archived
report, view, print and, if you have Word, email and even fax it!
Besides you can 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 or play a sound file.

Advantages of using template:
Main body of your customers will use their favourite email program for sending reports, so they should not get used to a new emailing program or some sort of Clarion window simulating New message window of emailing program As with any other email, Outlook Express will put sent reports into Sent Items folder so user will automatically have log of all sent reports in the form they are used to. When Received, report is immediately available for reading or printing so users should not do research to figure out what say .PDF means... Optionally report can be duplicated in attached RTF or report can be sent as RTF attachment only. Windows WordPad (95-XP) opens them. Report can be saved to disc in RTF format. In this mode you will see just created RTF in default Windows RTF editor and will be able to save it anywhere and with any name you like. Optionally you can do it in silent mode. As to technical side, EmailReport as all our templates is a white box template (no magic DLL to ship with all of your applications) Compatible with Clarion 5, Clarion 5.5, and Clarion 6.3 Legacy It does not need or do any changes to either Clarion native or 3d party templates. It's one of our taboos! Compatible with all major 3d party report templates: CPCS, RPM, DAS/ Tintools previewers, and Icetips previewer New embed is added, to allow you using this template with report templates other than Clarion, CPCS, RPM, DAS, Tintools, Icetips previewers or to change default template behaviour for those supported templates Network friendly - can be run by many network users simultaneously New features in version 6.1 Landscape report support Direct support for Icetips previewer No need to manually select basic report template Option to send not only report in RTF attachment, but also any other attachment(s) with your emails Option to define email priorities (High, Low, Normal) new internal help True multi-dll support

Installation

Run the installation wizard. It will guide you through a few simple steps. That is it.
IMPORTANT: If you are using Clarion 5 or 5.5, after selecting Clarion5 or C55 directory wizard
will offer you to install it into C:\Clarion5\Clarion6 or C:\C55\Clarion6 directory respectively.
So do not forget to get rid of last \Clarion6. But even if you do - it is not a problem.
Just uninstall template and run installation once again.
To start using template you have to manually register it.
Here is Instruction: Open Clarion (no application must be open).
Go to menu Setup -> Template Registry ->Register. Select new template
emlrptlg.tpl and then hit Open button.
View animated reminder on how to do that - Registering Template
(built with our JAVA Animated Help Builder).

Using Template
Global Extension Template
First of all you have to install global EmailReport extension template into your
application containing report(s) you want to email (no matter DLL it is or EXE)
In multi-dll application this extension is supposed to go into the main definition
app as well as in all apps with emailed reports.
Optionally you can define email background colour here one for all reports.
Later you can override it for any report you like (see picture below).
EmailReport supports global image shrinking. But you have an option
to override it locally for each report.
We added this shrinking feature for developers who are kin
on printing emails or eager to send landscape reports.
The rule of thumb - the more you shrink image the worse
quality of image you have, so use this option with care. But in some cases it'll
help you to print email more economically or fit wide report into email body.
You can try changing report fonts. Bold font always gives much better
performance. And shrinking almost has not got any influence on
quality of printed email.



The first 2 checkboxes allow you to optionally include prototypes for 2 API and C
functions required by template. Template does need them, but many other
3d party templates use them as well so EmailReport can use those foreign prototypes.
As to the second couple of checkboxes (the picture).
If the first checkbox is ON - RTF attachment will be generated.
The second - email body will be cleared. This feature maybe used
for instance if you know that majority of your clients will read emails
with say Netscape emailer.
Shrink reports prompts allows you to define one shrinking factor for all
reports in this application. You can use either numbers or your variable here.
You have an option to override it locally for each report.
You have to keep in mind that RTF uses the same shrinking factor as does
image in email body. And as far as RTF is concerned, you can show
your reports organized in rows and columns like in Word print preview.
The only thing you need to do for that - to apply 10% shrinking factor or so.
The last 2 prompts are optional. These are internal RTF document property.
So your customers will never see them. Nevertheless you can leave here
your "signature" if you want to.
By default template creates subdirectory \VH\ under your working directory
to keep temporary files. On some networks it can cause problems.
So the last prompt is the place where you can override this default behaviour.
Template creates global variable associated with this prompt GLO:WorkingDir
So you can specify any other directory like that: GLO:WorkingDir = 'C:\Temp'
In this case template will use C:\Temp on each workstation to build all
required files. Even if this directory does not exist, 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 that directory structure.
And if you do not use this variable template will work as always, that is
it will create 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 might need it when using non-standard reports to estimate
those picture sizes. Do not forget to sent it OFF before program release.
Though even if you do, it will not cause any inconveniences to your end-users.
The only difference it makes - their working directory will be a little bit larger.

Procedure Extension Template
Picture below shows all settings you have to define in report extension.
To open a Tab other than first just move the cursor on top of it.

General Tab
Report behaviour depends on one global variable only - GLO:NoEmail
You can use either numbers or pre-defined equates. We put them on the last tab
so you can copy and paste them into your code from there:
0 - EREQ:Email !Email in Body and RTF 1 - EREQ:Print !Print as ordinary report 2 - EREQ:Save !Preview RTF (and save manually) 3 - EREQ:Silent !Save silently 4 - EREQ:EmailInBody !Email in Body only 5 - EREQ:EmailInRTF !Email in RTF only
So it is a sort of EmailReport Global Request. In other words, if you say:
GLO:NoEmail = EREQ:EmailInBody; YourReport() - report will be emailed
in email body etc.
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 current report procedure.
It is important to stress that this is just a suggestion. So if you want,
you can reselect any other report template. You might want to do it only in exceptional
situations. For instance when you want to apply embed template to solve some 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 those directly supported templates
in Clarion/Examples/EmlRepLg* 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 directly supported (Clarion, CPCS, RPM, DAS, Tintools, and Icetips),

we would strongly recommended you to download free shareware version

of template to make sure it will work. You have to selects Other from the Basic

report template prompt and use EmailReport embed template. You should do the

same if you want to use this embed in one of supported report templates. In

template examples you can find how this embed can be used. You might want to

use template this way to satisfy some unusual requirements of your customers.

For instance to email and print report at the same time, or print and

save report into RTF. For this scenario you can optionally use another handy

feature of template. If you are going to employ EmailReport embed template say

with CPCS you first select CPCS as the basic report template and then insert

EmailReport embed template. You will find that all embed prompts are automatically

populated so you should not look for those variables in report code.

After this you should change basic report template to OTHER to disable execution

of default sequence. Otherwise template will try to email report twice - first with

default template code for CPCS in this case and then with embed template code.

Email Tab

It goes without saying that EmailTo, CC and BCC use the same format.

We employed special type of template prompt for them - expression.

So you can either hardcode them or build as a combination

of your fields. You can populate this prompt from any variable as well.

Just follow that simple specification below and standard Clarion syntax.

For your convenience we put the Example textbox

(not used by template) with few standard EmailTo prototypes. So you can copy

and paste any of examples and just replace our field names with yours.

Both EmailTo and Subject fields should be valid Clarion strings or expressions. Use

lookup buttons to find and append any filed from your Application like you do for formulas.

Optionally you can define images to use for navigation up and down arrows.

We ship a number of arrow GIFs with template:

It goes without saying you are welcome to use any others.

IT'S VERY IMPORTANT to remember that those images should be available at runtime.

So you should ship them with your application either in the working directory or in a

subdirectory of your working directory (where the main EXE is).

Though it is still not the end of the World if you have forgotten to ship them -

template in this case will replace them with "No frills" arrows which used to be

in all previous versions of EmailReport up to 2.3.

You can play audio files in your emails as well. You have 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 have to ship them with your application.

From our experience not all users appreciate this feature. So it's better

to show them such 'talking' emails first :-)

Besides you can define email priorities. Template understands only 3 words

here: High, Low, and Normal. So you can either put there one of those words

with quotes ('High' etc.) or use your STRING primed to either of those words.

If this prompt is not defined or there is a typo - priority defaults to Normal.

Report Tab

Here you can suspend global setting and to NOT generate RTF file.

You can specify name of 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 variable just put it's name.

or find it from lookup button. No exclamation marks are required!

You have to keep in mind that RTF using the same shrinking factor as does

image in email body.

RTF path prompt allows you to define where in your system you want

saved report to go (in the silent mode). It should be full path like:

'C:\Temp\Reports'. If this directory does not exists - template will try to

create it. It will even create nested directories for you! So if you prime

this variable to say 'C:\a\b\c' you will find this directory stricture and

saved report in the last \c directory.

You can define 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 image the worse

quality of image you have, so use this option with care. But in some cases it

will help you to print email more economically or fit wide report into email body.

You can try changing report fonts. Bold font always gives much better

performance. And shrinking almost has not got any influence on

quality of printed email.

Starting from version 6 you have full control of report sizing (both in Body and RTF).

By default template supports A4 reports. So the only thing you have to

do to them is to specify if report has Landscape layout.

To define report margins (for RTF) and report width and height template generates and

uses 4 global variables: GLO:RTFleft, GLO:RTFtop, GLO:RTFwidth, and GLO:RTFheight.

Those 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.

Do not forget to multiply it by 1000. It is important to understand that all

that should be done only if you use non-standard report sizing. You will know it

immediately because improper sizing dramatically decrease report quality.

So if you see something like that - time has come to check report sizes:

Otherwise you can completely ignore Position Group.

The type of prompt used for all 4 size variables

lets you define them either with variable or implicitly as a number.

So you can use predefined variables. You can

define and use your own variables for that. At last you can just

put a margin value right into corresponding prompt. As long as you follow

standard Clarion syntax you won't have any compile errors.

Body Note Tab

Optionally you can define a heading comment on the Body Note tab. Just follow plain

Clarion syntax and build any letter you like. Especially this option might be useful

when you send report as RTF attachment only. So you could explain here what to do

with this attachment.

Everything you add here goes directly into 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.)

If you like doing things in hard way you can consult HTML

and MIME documentation. For all other people here is a simple tip.

Use your Outlook Express for visual design. Just create new

message with it, insert images, text with any font you like etc. and then

Save it As a EML file. Done! Now you can open this file with any text editor

(say Notepad) and copy and paste HTML tags one by one. Just remember

that each tag should occupy one line in the body queue.

This restriction comes from the way we build message body, not from HTML syntax.

To make life easier we 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 one more thing to keep in mind - template stores that note in EREQ:BodyQue

global queue. So for extra flexibility you can completely ignore Body Note template Tab

and populate this queue directly from special embed: EmailReport - After filing queues.

So just use usual queue handling:

FREE(EREQ:BodyQue)
ERQ:Line = 'Line No 1'
ADD(EREQ:BodyQue)
ERQ:Line = 'Line No 2'
ADD(EREQ:BodyQue)
ERQ:Line = 'Line No 3'
ADD(EREQ:BodyQue)

If you omit FREE() function call, template will append those lines to

whatever you have already specified in the Body Note template prompt.

Attachments Tab

EmailReport takes care about Reports in RTF attachment.

So this attachment prompt allows you to specify list of any other files

to be sent with your emails.

Like email body note, these attachments are stored in global queue (EREQ:AttachmentQue)

So for all emails you can use either template settings or populate this queue directly

from the same embed point. You can combine those 2 methods as well.

Something like this will do:

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

Equates Tab

It's just a place where you can copy predefined equates for pasting them

into your code. You can find here examples of Email address formatting as well.

We installed example into your Clarion*/ Examples/EmlRepLg

directory so for various settings you can investigate the source.

To compile our demo you need all 3d party templates.

So to go around this, you can find short versions of the demo

in respective subdirectories: Examples/EmlRepLg/CPCS etc.

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.

Conversion from previous versions

In order to proceed we had to do 2 changes to template which

might affect current users.

So firstly to make template truly multi-dll we had to redefine those

global variables differently:

GLO:NoEmail
GLO:NoPreview
GLO:RandNo
GLO:RTFname
GLO:RTFpath
GLO:RTFleft
GLO:RTFtop

Now they are true globals visible in all applications. So you can set main switch

GLO:NoEmail in one application and call report from another. It will work properly.

In previous versions such things were impossible. Unfortunately we cannot

delete the old variables in the Global data section. So you have to do it yourself.

So you should follow those steps to convert application:

1. Backup application

2. Open it and delete those 7 variables from Global data section.

3. If Clarion does not issue any messages that is it.

4. If you see message like: "?GLO:NoEmail control deleted from Main procedure"

it means you have used that variable on the Main window.

5. Write down names of all such procedures

6. Restore original application and save all those window definitions in

the Notepad (you can find it from procedure properties -> 3-dot

button next to Window ...).

7. Repeat step 2 and then replace changed by Clarion window definitions

with those just saved in Notepad

These steps will help Clarion to find those differently defined globals.

You can do it any other way. For instance text-export your procedures

and then import them back after deleting those global variables.

Secondly only if you use CPCS basic report template or Other,

you 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 might cause.

Actually we have made a multi-dll version long time ago

and have been giving that template on request as ver. 2.52

C6 is a huge mile-stone for all Clarion developers. And it looks like

everybody will have to do some sort of conversion to migrate into

that environment anyway. So we finally have decided - time has come

to proceed with those changes.

Users Tips (you are welcome to send your tips in this area!)

1. Remember to select the Report Template Used (clarion, cpcs...).

2. If you are not using a global switch (as in the example app) reset

GLO:NoEmail to 1 at end of report (GLO:NoEmail = 1) to default to printing.

3. To save the RTF file do not forget to specify path in GLO:RTFPath

and file name GLO:RTFName (without path and extension)

4. You CANNOT use the C-style terminology IF ~GLO:NoEmail now :-(

It must be referred to either by equate or 0,1,2 or 3.

5. On network all drivers should be mapped

6. For Fomin report builder you have to select Clarion from the Basic

Report Template combo (see picture below).

7. All template prompts follow standard Clarion syntax. So do not try to put

exclamation mark in front of them! Or leave string without the quotes.

Or wrap a variable in quotes etc.

8. With report templates not supported directly always choose Other

from the Basic template combo and apply EmailReport Embed template

9. To get some quick help you can hit any of those question-marked buttons

(picture below). It's new type of template help we've just developed,

so would you tell us please what you think of the new help

10.Latest WinXP issue. If you see email preview without Send button

it means you should apply MS patch for OE. The simplest way to

do it is to use Adobe version of it: adobeforums.com. To avoid

registration you can log in as guest.

Alternatively you can download original MS patch here: microsoft.com

but it is much harder to use it.

Move cursor on top of a Tab to open!