EmailReport Template Legacy

Introduction

EmailReport for Clarion 5-10... Legacy Template allows you to send Clarion reports in the user-friendliest way - right in the body of email messages. It is compatible with Legacy Clarion Report, CPCS, RPM, DAS, Tintools, and Icetips report templates. You can duplicate reports in RTF format to print  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 illustrates 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 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 messages, rather than as an attachment of some kind.
It makes the report immediately available to the email addressee. There is no need for him/her
to look for a version of MS Word to open the attached *.DOC. Nor should he/she download
and install Acrobat reader (9MB or so) to view *.PDF file attachments.
This template is designed to work in conjunction with Outlook Express
which these days is a part of Windows OS. So every Windows user has it.
Users still can employ any emailing program they like for their ordinary emailing,
but for sending Clarion reports EmailReport the template will automatically invoke Outlook Express.
And if they wish to have sent emails in another email program, they can
from simply 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 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, a report can be duplicated
as an attachment of RTF type. This file can be opened/printed even
with Windows WordPad (95-v.7) program, so no 3rd party program is required.
MS Word (95-v.7) will also 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 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 directly into the email body or play a sound file.
 
Advantages of using the template:
  • The majority of your customers will use their favourite email program for sending reports,
    so they needn't get used to a new emailing program or a Clarion window
    simulating the New message window of an emailing program
  • As with any other email, Outlook Express will put sent reports into the Sent Items folder so
    the user will automatically have a log of all sent reports in the form they are used to.
  • Once received, a report is immediately available for reading or printing so users needn't figure out what say .PDF means...
  • Optionally a report can be duplicated in attached RTF or can be
    sent as a RTF attachment only. Windows WordPad (95-v.7) 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 it anywhere and with any name you like. You also have the option to do
    it in silent mode.
  • As to the technical aspect, EmailReport, like all our templates, is a white box template
    (no magic DLL to ship with all of your applications)
  • Compatible with Clarion 5-10... Legacy
  • It does not make any changes to either Clarion native
    or 3rd party templates. It's one of our taboos!
  • Compatible with all major 3rd party report templates: CPCS, RPM, DAS/
    Tintools previewers, and Icetips previewer

  • We've added a new embed, 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 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. 
Just uninstall template and re-run the installation.
To start using the template you'll need to manually register it.
To do this: Open Clarion (no application must be open). 
Go to menu Setup -> Tools (Setup) -> (Edit) Template Registry -> Register.
Select the new template emlrptlg.tpl and then hit the 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 the 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 the global EmailReport extension template into your
application containing the report(s) you want to email (DLL or EXE)
In multi-dll applications this extension is goes 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 an option
to override it locally for each report.
We added this shrinking feature for developers who wish
to print emails or send landscape reports. 
The rule of thumb - the more you shrink the image the worse
the quality of the image, so use this option with care. But in some cases it'll
help you to print email more economically or fit wide reports into the email body.
You can try changing report fonts. Bold font always gives much better
performance. And shrinking has virtually no influence on the
quality of the printed email.
The first 2 checkboxes allow you the option of including prototypes for 2 API and C
functions required by the template. The template doesn't need 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 - the RTF attachment will be generated.
The second - the email body will be cleared. This feature maybe used
for instance if you know that the 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 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 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 a subdirectory \VH\ under your working directory
to keep temporary files. On some networks this 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 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 that directory structure.
And if you do not 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 might need it when using non-standard reports to estimate
picture sizes. Don't forget to sent it to OFF before program release.
Though even if you do, it won't cause issues for your end-users.
The only difference it makes is that their working directory will be slightly larger.
Procedure Extension Template
The picture below shows all settings you need 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 is a sort of EmailReport Global Request. In other words, if you say:
GLO:NoEmail = EREQ:EmailInBody; YourReport() - the 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 the 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 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've provided 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 using 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'll need 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 supported report templates. In the
template examples you will see how this embed can be used. You may wish to 
use the template this manner to satisfy some unusual requirement 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 have the option of using another handy 
feature of the template. If you are going to employ the 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 the execution
of the default sequence. Otherwise the template will try to email reports twice - first with the
default template code for CPCS in this case and then with the 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 these - expression.
So you can either hardcode them or build as a combination
of your fields. You can also populate this prompt from any other variable. 
Just follow the simple specification below and standard Clarion syntax.
For your convenience we've put the Example textbox
(not used by the template) with 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
lookup buttons to find and append any field from your Application as you would 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 free to use any others.
IT'S VERY IMPORTANT to remember that those images should be available at runtime.
So you'll 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 forget to ship them - the
template in this case will replace them with a "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'll 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 :-)
Besides this, you can define email priorities. The template understands only 3 words
here: High, Low, and Normal. So you can either use 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 a RTF file.
You can specify name of a 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 put it's name.
or find it from lookup button. No exclamation marks are required!
You need to bear in mind that RTF uses the same shrinking factor as 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:
'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
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 RTF file name and path for saving reports.
The rule of thumb - the more you shrink the 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 give a much better
performance. And shrinking almost 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 to
do 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 by 1000. It is important to understand that all
this need only be done if you use non-standard report sizing. You will know
immediately because improper 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
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. At last you can just
put a margin value right into the corresponding prompt. So long as you follow
standard Clarion syntax you won't have any compile errors.
Body Note Tab
You have the option of defining 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 you send reports as RTF attachment only. So you could explain here what to do
with this attachment.
Everything you add here goes directly into the embedded email HTML file.
So you can also use HTML tags. (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 others here is a simple tip.
Use your Outlook Express for visual design. Simply use it to create a new
message, 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 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 on more than one line - this tag will get broken.
by the new-line tag inserted by the 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 the 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(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 a list of any other files
to be sent with your emails.
Like the email body note, these attachments are stored in a global queue (EREQ:AttachmentQue)
So for all emails you can either use template settings or else populate this queue directly
from the same embed point. You can also combine these 2 methods.
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 a place where you may copy predefined equates for pasting them 
into your code. You can find here examples of Email address formatting as well.
We've installed examples into your \ DOWNExamples\EmlRepLg\
Or Clarion7(8,9,10...)\Lessons\EmlRepLg in Clarion 7-10....
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 a short version of the demo
in respective subdirectories: Examples\EmlRepLg\CPCS etc.
IMPORTANT: In email mode reports cannot go without a 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 make 2 changes to the template which
may 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. 
In previous versions such things were impossible. Unfortunately we cannot
delete the old variables in the Global data section. So you'll need to do it yourself.
Follow these simple 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 do this in other ways too. 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.
We actually 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've finally decided that the time has come
to proceed with these changes.
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 don't forget to specify the 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 a 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). This is a new type of template help we've just developed,
    so please let us know what you think of the new help
10.Latest WinXP issue. If you see the email preview without a Send button
    it means you should apply MS patch for OE. The simplest way to
    do this is to use the Adobe version of it: adobeforums.com. To avoid
    registration you can log in as a guest.
    Alternatively you can download the original MS patch here: microsoft.com
    but it's much harder to use.
11. WinXP issue II - No Send Button on new email. You are welcome to download 
    a program of ours (Clarion 6 code is included) to reset the respective registry setting.
Move cursor on top of a Tab to open!

Copyright (C) 2015 Vivid Help Systems Pty Ltd