EmailReport Template 7.7

ABC/Legacy

Introduction

EmailReport Template for Clarions after 8 is now using *.PNG images instead of Aldus *.WMF that makes it universally compatible with all major Email Programs (Thunderbird, MS Outlook etc.), can be read on any device (not just MS ones as before) and still allows you to send Clarion reports in the user-friendliest way - right in the body of email messages. It is compatible with Clarion Report, CPCS, RPM, DAS, Tintools, and Icetips report templates. You can duplicate a report in RTF format to print it from any email program and/or OS or send RTF only. Besides you can use the template just for saving reports to disc in this universal format. No email settings are required from end-users.

The picture on the right gives some idea of how the template works. Do whatever you want, but please don't hit the arrow!!! Download our 'Try before buy' free version of the template and test it right in your own application. You can also have a quick look at emails generated by the template. 
Unlike all other templates, the EmailReport sends Clarion reports right in the body
of email messages, rather than as an attachment of some kind.
It makes reports immediately available for email addressees. There is no need for him/her
to look for a version of MS Word to open any attached *.DOC. Nor should he/she download
and install Acrobat reader (9MB or so) to view *.PDF file attached.
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).
Now, with a new embed template, EmailReport can be used with a
much wider range of report templates.
To ensure that your customers will be able to print/preview an emailed report with
any email program and/or Operating System, the report can be duplicated
as attachment of RTF type. This file can be opened/printed even
with Windows WordPad program, so no 3rd party program is required.
Of course MS Word, if installed, will also do the job.
Download generated by template RTF file for testing.
Moreover, EmailReport is much more than just a report emailer.
You also have the option to use 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 Word, email and even fax it!
Besides this, 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 :-).
There is also the option to put a note right in the email body or play a sound file.
 
Advantages of using the template:
  • Template is compatible now with all major Email Programs (Outlook, Thunderbird etc.)
    and generated emails can be viewed on any device.
  • The majority of your customers can use their favourite email program for sending reports,
    so they needn't use a new emailing program or a Clarion window
    simulating a New message window of the emailing program
  • As with any other email, Outlook Express will put sent reports into Sent Items folder so
    the user will automatically have a log of all sent reports in the form they are used to.
  • When Received, the report is immediately available for reading or printing so users don't 
    have to figure out what say .PDF means...
  • Available options mean that the report can be duplicated in attached RTF or 
    sent as RTF attachment only. Windows WordPad opens them.
  • Reports 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 them anywhere and with any name you like. You can also do
    this in silent mode.
  • As to the technical side, like all our templates EmailReport is a white box template
    (no magic DLL to ship with all of your applications)
  • Compatible with Clarions > 8... ABC/Legacy
  • It does not make any changes to either Clarion native
    or 3rd party templates. It's taboo!
  • Compatible with all major 3rd party report templates: CPCS, RPM, DAS/
    Tintools previewers, and Icetips previewer
  • New embed is added, to allow you to use 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
  • Landscape report support
  • Direct support for Icetips previewer
  • No need to manually select basic report template
  • Option to send not only reports 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
  • 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 Template

Global Extension Template
First of all you have to install the global EmailReport extension template into your
application containing the report(s) you want to email (no matter if DLL 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.
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).
EmailReport supports global image shrinking. But you have the option
to override it locally for each report.
We've added this shrinking feature for developers who wish
to print emails or to send landscape reports. 
The rule of thumb - the more you shrink the image the worse
quality of image you have, 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.
The first 2 checkboxes allow you the option of providing prototypes for 2 API and C
functions required by the template. The template requires them, but many other
3rd party templates use them as well so EmailReport can use these foreign prototypes.
As to the second couple of checkboxes (see picture):
If the first checkbox is ON - RTF attachment will be generated.
The second - email body will be cleared. This feature may be used
for instance if you know that the majority of your clients will read emails
with say Netscape emailer.
The shrink reports prompt allows you to define one shrinking factor for all
reports in this application. You can use either numbers or your variable here.
You have the option to override it locally for each report.
You have to bear in mind that RTF uses the same shrinking factor as does the
image in the 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 is to apply 10% shrinking factor or so.
The next 2 prompts are optional. These are internal RTF document properties,
so your customers will never 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 it may cause problems.
So the last prompt is the place 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 as: 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 does not 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 that directory structure.
And if you don't use this variable the 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/PNG report pages in the working directory.
You might 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 be an issue for your end-users.
The only difference is that their working directory will be slightly larger.
Procedure Extension Template
The picture below shows all settings you have to define in the report extension.
To open a Tab other than the first just move the cursor over it.
General Tab
Report behaviour depends on one global variable only - GLO:NoEmail
You can use either numbers or pre-defined equates. We've 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 functions as an EmailReport Global Request. In other words, if you say:
GLO:NoEmail = EREQ:EmailInBody; YourReport() - report will be emailed
in the 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 wish to
you can reselect any other report template. You may wish to do this only in exceptional 
situations. For instance when you want to apply an 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\EmailRep directory so you can investigate recommended
template settings there.
IMPORTANT: If you want to try using this template with any report template
other than those directly supported (Clarion, CPCS, RPM, DAS, Tintools, and Icetips),
we would strongly recommended that you download a free shareware version
of the template to make sure it will work. You have to select Other from the Basic
report template prompt and use the EmailReport embed template. You should do the
same if you want to use this embed in one of the supported report templates. In
the template examples you can see how this embed can be used. You may wish to 
use the template in this way to satisfy any unusual requirements of your customers.
For instance to email and print reports at the same time, or print and
save reports into RTF. For this scenario you can use another handy 
feature of the 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 the
EmailReport embed template. You will find that all embed prompts are automatically
populated so you needn't look for those variables in the report code.
After this you should change the basic report template to OTHER to disable execution
of default sequence. Otherwise the template will try to email reports 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've employed a 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 the simple specification below and standard Clarion syntax.
For your convenience we've put the Example textbox
(not used by template) with a few standard EmailTo prototypes. So you can copy
and paste any of the examples and just replace our field names with yours.
Both EmailTo and Subject fields should be valid Clarion strings or expressions. Use the
lookup buttons to find and append any field from your Application as you do for formulae.
As an option you can define images to use for navigation up and down arrows.
We ship a number of arrow GIFs with the template:
Of course you are welcome 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).
Though it is still not the end of the World if you have forgotten to ship them - the
template in this case will replace them with a "No frills".
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 just remember 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 :-)
Besides this, you can also define email priorities. The template understands only 3 words
here: High, Low, and Normal. So you can either insert 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 the global setting to NOT generate RTF file.
You can specify the name of the RTF attachment file either from a variable or
by hard-coding it from the prompt (using say 'ReportCopy' will create
attachment ReportCopy.rtf). If you use a variable just put its name.
or find it from the lookup button. No exclamation marks are required!
You have to bear in mind that RTF uses the same shrinking factor as does the
image in the email body.
RTF path prompt allows you to define where in your system you want the
saved report to go (in the silent mode). It should be a full path like:
'C:\Temp\Reports'. If this directory doesn't exist - the 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 structure and the
saved report in the last \c directory.
You can define the image shrinking factor applicable for both body and RTF reports
and specify variable names for the RTF file name and path for saving 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
will help you to 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 the email.
You have full control of report sizing (both in Body and RTF).
By default the template supports A4 reports. So the only thing you have to
do to them is to specify if the report has Landscape layout.
To define report margins (for RTF) and report width and height the 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 
this is only necessary if you use non-standard report sizing. You will know 
immediately because improper sizing dramatically decreases report quality.
So if you see such poor quality you know you need 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 a variable or implicitly as a number.
So you can use predefined variables. You can 
define and use your own variables for this. 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
As an option you can define a heading comment on the Body Note tab. 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 can explain here what to do
with this 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.)
If you enjoy doing things the hard way you can consult HTML
and MIME documentation. For all other individuals here is a simple tip.
Use your Outlook for visual design. Just create a new
message with it, insert images, text with any font you like etc. and then
Save it As an 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 the message body, not from HTML syntax.
To make life easier we've put a new-line tag after each line of HTML
So if you try to split a tag onto more than one line this tag will get broken
by the new-line tag inserted by template.
And one more thing to bear in mind - the template stores this 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 the 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, the template will append those lines to
whatever you have already specified in the Body Note template prompt.
Attachments Tab
EmailReport takes care of Reports in RTF attachment.
So this attachment prompt allows you to specify list of any other files
to be sent with your emails.
Like the email body note, these attachments are stored in the 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
This is the 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've installed an example into your Clarion9(10,11...)\Lessons\EmailRep
So for various settings you can investigate the source.
To compile our demo you need all 3rd party templates.
So to go around this, you can find short versions of the demo
in respective subdirectories: Examples/EmailRep/CPCS etc.
IMPORTANT: In email mode reports 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 the template which
might affect current users.
So firstly to make the 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 the main switch
GLO:NoEmail in one application and call reports 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.
Simply follow these steps to convert the 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 also do this is in other ways. 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 may cause.
Actually we made a multi-dll version a while 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 decided that the time has come
to proceed with those changes.
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.
 
Users Tips (you are welcome to send your own tips to 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
Move cursor on top of a Tab to open!

Copyright © 2025 Vivid Help Systems Pty Ltd