CapeSoft.Com
Clarion Accessories
Premiere
Documentation
CapeSoft Logo

CapeSoft Premiere
Documentation

Download Latest Version FAQ History Templates
Installed Version Latest Version

Introduction

Please Note: Premiere requires StringTheory

From time to time a discussion will arise in the newsgroups about the "look" of a program. What can Clarion programs look like if you move beyond the plain default settings. In response I'll usually post a link to one of our commercial apps (https://www.veculim.com/Screenshots.htm) to act as a visual aid to some of the topics I discuss in reply. Lots of interesting discussion will then take place, but sooner or later someone asks;

"What Print Preview are you using?"

(You can see the print preview screen-shot here https://www.veculim.com/Screenshots.htm#preview). The answer is that it's a modified version of the previewer that's built into our RightReports product. Which of course is not terribly helpful if you are not using Right Reports in your own program. (And RightReports is a bit expensive to purchase just for the previewer.)

Then I needed a print previewer for a program that doesn't use RightReports. So I took the time to extract the previewer into a separate accessory, and along the way added some features to it, and tidied it up a bit. One thing lead to another, more features were added, and so Premiere was born.

Premiere is a PrintPreview procedure that replaces the default preview procedure in your application.
It exists as a procedure in your app tree, so the look of the procedure can be completely consistent with your application. Plus it allows your user more control over the output - they can select a subset of pages and then save that to a PDF [1], Excel or Word[2] send to someone else via email [3], upload to a cloud drive [4], print multiple copies and so on.

[1] Saving to a PDF requires a PDF engine. The SoftVelocity engine, Tracker's PDF-Tools version 4.1, and Klarisoft's wPDF are all supported.

[2] Saving to an Excel or Word document requires an Office Engine. Currently only CapeSoft's Office Inside is supported. If you are using an alternate engine that has the ability to create office documents from a Report then ask that supplier to contact us with a view to adding support for it in Premiere.

[3] Sending via Email requires NetTalk 8 (any level) or later, or an alternative SendEmail procedure.

[4] Uploading to a Cloud drive requires NetTalk 10 (any level) or later and  File Explorer, or an alternative UploadFileToCloud procedure.

Webinar

A ClarionLive webinar, #386, was made of the Premiere release. It is available here.

Requirements

CapeSoft (and others) have been making accessories for a long time, and the accessory toolbox includes all sorts of useful functionality. A product like Premiere is a natural candidate to make use of these additions. It has however been carefully constructed so you can use as many, or as few, of these optional extras as you desire.

Specifically supported engines are listed below as optional requirements. However the system is constructed so that support for more engines can be easily added if there is demand for it. So if you don't see your favorite engine listed feel free to contact us for more information.

JumpStart

Premiere

  1. Add the StringTheory Global Extension to the application.
  2. (Optional) Add the HyperActive Global Extension to the application. [3]
  3. Add the Premiere Global Extension to the application.
  4. On the General tab, Import the Premiere, PremiereGetData, PremiereCreateExcelFromQueue, PremiereCreateWordFromQueue and PremiereCreatePDFFromQueue procedures. [2]
  5. Add the Global Extension Call_Premiere_Previewer - Call Premiere from all reports to the application.[1]
    (This adds the Previewer call to all reports. If you want to do this manually then see Manual Previewer Calls below.)
  6. (Optional) On any report go to the extensions and set extra settings there for the Premiere previewer.

PDF Engine (optional)

  1. Add the global extension of your PDF Engine to the application. It should be one of
     
    • The SoftVelocity ReportToPDFGlobal extension
    • Tracker's PDFXToolsGlobal41 extension, or
    • Klarisoft's wPDF Global extension. Fill in the License details as normal here.

  2. Some PDF Engine specific features can be found in the PremiereCreatePDFFromQueue procedure. You can use these settings to tune the creation of the PDF, depending on your engine.

The PremiereCreatePDFFromQueue procedure will detect whichever of these extensions you have added, and generate code appropriate to that engine.[5]

If you do not have any PDF engine in the application then the Save As PDF functionality will be disabled.

Office Engine (optional)

  1. Add the global extension of your Office Engine to the application. It should be one of
     
    • CapeSoft's Office Inside

The PremiereCreateExcelFromQueue and PremiereCreateWordFromQueue  procedures will detect whichever of these extensions you have added, and generate code appropriate to that engine.[5]

If you do not have any Office Engine in the application then the Save As Excel AND Save As Word functionality will be disabled.

Add NetTalk Email (optional)
        (If you don't already have a NetTalk SendEmail procedure in your app)

  1. Using the \Examples\NetTalk\Email\Demo app as a reference;
  2. Copy (Copy and Paste) the EmailLog and EmailSettings tables from the NetTalk demo dictionary to your dictionary.
  3. Open your application. Import the SendEmail and UpdateEmailSettings procedures from the NetTalk demo app. (You may also want to import the BrowseEmailLog procedure)

No Email

If you are not using NetTalk (or any email procedure) in this application, go to the Premiere Procedure, Extension Templates, and on the Premiere Extension, Options tab, turn off the CheckBox Allow Send Email from Previewer.. [4]

If you are using an alternate Email procedure (not NetTalk) then you can leave this option on, and create the SendEmail procedure appropriately. See below for instructions.

Add NetTalk File Upload to Cloud (optional)
        (If you don't already have a NetTalk UploadFileToCloud procedure in your app)

This feature allows the previewer to upload any report (in any of the export formats, PDF, Excel etc) to the user's cloud drive. Supported clouds are Dropbox, GoogleDrive, and Microsoft OneDrive. Since these services use OAuth authentication it is necessary to include FileExplorer in the application (as it is used by the OAuthLogin procedure). This feature also requires NetTalk 10 (any level), build 10.19 or later and jFiles.
  1. Using the \Examples\NetTalk\NetDrive\Demo app as a reference;
  2. Add the File Explorer Global Extension to your application, if it is not already there.
  3. Open your application. Import the UploadFileToCloud and OAuthLogin procedures from the NetTalk demo app.

No Cloud

If you are not using NetTalk (or any UploadFileToCloud procedure) in this application, go to the Premiere Procedure, Extension Templates, and on the Premiere Extension, Options tab, turn off the CheckBox Allow File Upload from Previewer.. [6]

If you are using an alternate UploadFileToCloud procedure (not NetTalk) then you can leave this option on, and create the UploadFileToCloud procedure appropriately. See below for instructions.

Hyperactive (optional)

  1.  Add the CapeSoft HyperActive Global Extension to the application. (If Multi-DLL this only needs to be in the Data DLL.)
  2. Go to the PremiereCreatePDFFromQueue procedure, to the Local Extensions, and add the HyperActive Local Extension
  3. Go to the Properties of the Hyperactive Local Extension, to the Controls tab, and Insert a control there. Select ?Answer from the list of controls. You can leave the other settings at their default values.

Multi-DLL

The above instructions are for a single Exe application. If you have a multiple-application suite then there are a few additional instructions that need to be noted.
  1. You will need to add the Premiere Global Extension to the data DLL, and any other DLL  (or EXE) that contains a Report.
  2. In the Data DLL (the DLL which exports the dictionary) go to Premiere Global Extension, To the Multi-DLL tab, and tick on the option to Export Premiere Classes from this DLL. (You will do the same for the StringTheory global extension, and the Hyperactive Global Extension, if you have them.)

    In all the other apps with the Premiere Global Extension (including any EXE apps with the global extension) make sure the option This is part of a Multi-DLL program is ON and the Export Premiere Classes from this DLL option is OFF.
  3. In the Data DLL Make sure the Premiere Procedure has the EXPORT option ticked on.
  4. You Do NOT need to import the Premiere Procedures into other DLL's or the Exe. Only the Data DLL needs these procedures.

Notes

[1] Adding a Second Global Extension
 When adding the second Premiere global extension (which adds the Local Extension to all the reports) you need to first select the main Activate CapeSoft Premiere extension and then click the Insert button. If you have some other extension selected then the Call_Premiere_Previewer extension will not be available in the template list.

[2] Importing Premiere Procedures
The easiest way to import the procedures is to click the Import Procedures button on the Global Extension.
This imports a TXA file, with 5 procedures into your application.  Some builds of Clarion can struggle with TXA files, so if you have any problems, import the procedures directly from one of the example applications. The procedures you want are Premiere, PremiereCreateExcelFromQueue, PremiereCreateWordFromQueue, PremiereCreatePDFFromQueue and PremiereGetData.

Clarion 9/10 Important Note:
When importing into some builds of Clarion 9 and Clarion 10, the Parameters setting is not set. If this is the case you get compile errors when compiling for the first time. Simply "visiting" the properties of the three procedures in question (see list in paragraph above) solves the problem.

[3] Possible Import Errors
The example applications, and Premiere TXA's include a Hyperactive extension in the PremiereCreateExcelFromQueue, PremiereCreateWordFromQueue and PremiereCreatePDFFromQueue procedures. If you do not have Hyperactive then this will trigger an error on import;
GEN: Unknown Template type HyperActive(HyperActive)
This error can be ignored.

If you get the error
Unknown Variable %HaDefaultBright
(and several like it) when importing the procedures you have Hyperactive, but the global Hyperactive Extension is not in this application. Add the global extension to get this feature.

[4] Possible Compile Errors
If you do not import or create a SendEmail procedure, and you do not tell Premiere that Send Email is not available, then you will get an error when compiling
No Matching Prototype Available
The error will be on a line of code reading;
Return SendEmail(pEmail)
If you get this error then either follow the steps above to add Email support, or tick on the option to turn off email support..

[5]Export Engine Overrides
By default Premiere will detect your PDF and Office engines by inspecting the Global Extensions. If you wish to override this detection the see the Global Extension template, Options tab.

[6] Possible Compile Errors
If you do not import or create a UploadFileToCloud procedure, and you do not tell Premiere that Upload to Cloud is not available, then you will get an error when compiling
No Matching Prototype Available
The error will be on a line of code reading;
Return UploadFileToCloud(pCloud)
If you get this error then either follow the steps above to add Cloud support, or tick on the option to turn off cloud support..

Upgrading from an earlier Premiere version

Repopulating Premiere Window (3.20 or later)

The Premiere window has a number of new control on it in build 3.20. For this reason it is recommended (although not required) for the control template on the window to be repopulated, or for the Premiere procedure to be re-imported from one of the examples.

If you are using the Clarion built-in resizing template, and you have not added other custom functionality to the window, then re-importing the procedure from an example app is probably the easiest approach.

If you are using an alternate resizer, or other custom functionality on the window, then simply deleting the control template, and repopulating it on the window is probably the better approach. You may then need to add the new controls (Pages entry field, and upload buttons) to the resizer etc. The window will also likely need to be made slightly wider to accommodate the new fields.

Adding Cloud Support (3.20 or later)

  1. Add File Explorer Global Extension template (if it's not already there.)
  2. Import OAuthLogin procedure from ABCNetTalkFE or LegacyNetTalkFE examples.
  3. Import UploadFileToCloud procedure from ABCNetTalkFE or LegacyNetTalkFE examples.

    VERY IMPORTANT  : After importing Right-click on the UploadFileToCloud procedure and choose source. Find the line that starts with pParms.pClientId and change the pClientId and pClientSecret parameters to your own values. To get more information on these values see the NetTalk documentation.
  4. Re-import Premiere procedure from one of the examples.

Turning Off Cloud Support (3.20 or later)

Cloud support is turned on by default. If you do not have File Explorer, or do not want cloud support in the previewer, then go to the Premiere procedure, to the Premiere Print Preview extension, to the Options tab. Turn off the option there Allow File Upload From Previewer. Failure to do this step will likely incur the error;

No matching prototype available on
Return UploadFileToCloud(pCloud)

Extending PremiereGetData (3.40 or later)

As from build 3.40 the PremiereGetData procedure has been updated to get 2 items of data from the user, instead of just one.
This is primarily to support the entry of a file password when entering a filename.

Note that this update is REQUIRED whether you plan to use the password feature or not.

To upgrade this procedure;
  1. Open the app that contains the PremiereGetData Procedure
  2. Go to the Premiere Global Extension, click on the Import PremiereGetData Procedure button
  3. When prompted by the IDE select Replace All

Clarion Changes (very optional)

These suggested changes affect both ABC and Legacy programs.

If you are using the SoftVelocity PDF engine, and saving as a PDF, you can optionally choose to display a progress window as the report is converted to PDF.

This window is declared in the Clarion file \clarion\libsrc\win\abwmfpar.clw in the WMFDocumentParser.GenerateReport method. By default this window is pretty ugly, and probably does not match the look of your program. You can edit the window there (use Ctrl-D to open the window designer) to make it look better.

Example;

ProgressWindow WINDOW('Export Progress...'),AT(,,331,53),CENTER,FONT('Segoe UI',10),TIMER(1),DOUBLE
                 IMAGE,AT(6,7),USE(?ImageGenerator)
                 STRING('Exporting to'),AT(61,6,247,10),USE(?Progress:UserString),LEFT
                 PROGRESS,AT(61,27,247,10),USE(Progress:Thermometer),RANGE(0,100),SMOOTH
                 STRING('Page 0 of '),AT(61,15,114,10),USE(?Progress:PctText),TRN,LEFT
               END

You may also want to copy
\clarion\accessory\images\pvPDF.Ico to \clarion\images\EXP_PDF.ICO
so that the PDF icon on the progress window looks better.

Of course these changes will be overwritten by future Clarion installs, so will need to be repeated after updating Clarion. If the changes are not repeated then there is no functional penalty to your program, other than the progress window looking a bit ugly.

Third Party Support

The Call Premiere Print Preview template supports the Clarion Report Template for both ABC and Clarion (Legacy) applications. In addition to this it also supports the following other Reporting templates;

CPCS / Creative Reporting Tools

There are a large number of Creative Reporting Tools (nee CPCS) features, but the Premiere template should support CRT reports. If it does not support a CPCS report that you have automatically then please notify support@capesoft.com

RightReports

RightReports has built-in support for a number of different previewers.
To use Premiere with RightReports make sure you are using build 1.97 or later.
On the Right Reports Global Extension, Options Tab, select Premiere from the drop-list of previewer's available.

Fomin Report Builder

Premiere supports the FRB "RuntimeReport" procedure. If the user chooses the Printer as the output, and Preview is on, then the Premiere Previewer is displayed.

Translation Tools

Premiere supports AnyText directly. If you are using another translation tool then Premiere provides a method for translating any text used by the class. See Translations for more information.

PDF Engines

If a PDF engine is available, then a Save-As PDF option is available to the user on the preview screen. Currently supported engines are;

Office Engines

If an Office engine is available then a Save-As Excel and Save-As Word option is available to the user on the preview screen. Currently the only supported engine is CapeSoft's Office Inside. Suppliers of other engines (that support Report to Office functionality) can contact us to collaborate on support for other engines.

Email Engines

If an Email engine is available then an option to send the report as an email is available to the user on the preview screen. This requires a PDF or Office engine as well. Currently the only supported email engine is CapeSoft's NetTalk.   Suppliers of other engines can contact us to collaborate on support for another engine.

Cloud Engines

If a Cloud engine is available then an option to upload the report as a file is available to the user on the preview screen. This requires a PDF or Office engine as well. Currently the only supported cloud engine is CapeSoft's NetTalk.   Suppliers of other engines can contact us to collaborate on support for another engine.

Manual Previewer Calls

In most cases you will use the second Premiere Global Extension (Call Premiere Previewer) to add the necessary local extension to all report procedures. However use of this global extension is optional and you may prefer to add the Local extension to selected reports by hand.

To add the local extension simply go to the report and add the Call Premiere PrintPreviewer extension to the report. This extension supports most common report procedures.

If your report is a hand-coded procedure, then you will need to add the call to the Previewer manually from there. The syntax for the call is as follows;

Premiere (PrintPreviewFileQueue, pReport, pOptions)

The PrintPreviewFileQueue is the queue of WMF files as created by your report.
The pReport is the name of your report structure.
The pOptions is a group of type PremierePreviewerOptions. This parameter can be omitted.

You will need to declare the pOptions parameter in your procedure.
pOptions   Group(PremierePreviewerOptions).
The declaration of PremierePreviewerOptions is in Premiere.Inc.

For more information on the fields you can set in the group, see the section PremierPreviewOptions Group below.

The default Clarion previewer does not have the ability to print the report. The printing was done on the return from the previewer depending on the value (true or false) returned by the previewer. Since the Premiere previewer does the printing directly itself this additional code in the calling procedure can be removed.

PremierePreviewerOptions Group

The declaration of PremierePreviewerOptions is in Premiere.Inc.
The contents of the group are as follows;
Property Type Description
AllowCommas Byte If set to true then commas are allowed in filenames when creating PDF files. Note that NetTalk 10 does not allow commas in filenames, so the default value is false. If you are using NetTalk 11 or later then you can set this property to true. (See Previewer Control Template).
AllowPageSelections Long not currently used
AttachmentList String A semi-colon separated list of files that will be added to outgoing emails, in addition to the generated PDF or Office file.
Automatic Long If Automatic is set to true then the PremiereCreateFromQueue window is closed immediately after the file is created. If it is false then the PremiereCreateFromQueue will remain open when the file is created, allowing the user to note the name and location of the created file (and if Hyperactive is used, to click on the file name to open it.)

Note that Automatic is independent of HideWindow. It is possible to have HideWindow set to true (so the preview window is hidden), Destination set to 'F', and Automatic set to false. In this scenario the user will not see the preview window, but will see the PremiereCreateFromQueue window as the file is created.
Copies Long The number of copies to print. Only applies when Destination is 'P', or if the user clicks on the Print button. The user can override this setting by clicking on the Advanced Print Button.
Destination String Sets the destination of the report, if HideWindow has been set to true. Valid options are;
'P' -- Send the report to a printer.
'E' -- Send the report to email as a PDF Attachment.
'L' -- Send the report to email as a Excel Attachment.
'R' -- Send the report to email as a Word Attachment.
'F' -- Send the report to a PDF File.
'X' -- Send the report to a Excel File.
'W' -- Send the report to a Word File. (also 'D')
'G' -- Upload the report to Google Drive
'O' -- Upload the report  to Microsoft OneDrive
'B' -- Upload the report  to DropBox

If 'F' or 'E' (PDF File)  then a PDF engine in the application is required.
If 'X' or 'L' or 'D' or  'W' (Excel or Word) then an office engine in the application is required.
If 'E' or 'L' or 'D' then an email engine in the application is required.
If there is no PDF engine and no office engine then destination will be treated as 'P'.
If the field is set to another (invalid) value then it will be treated as 'P'.

The Destination string can contain multiple of the above characters. For example if it contains 'PEW' then it will be sent to the printer, emailed as a PDF, and create a Word file.
Disable String Disables some functionality in the previewer. This can be used on a report-by-report basis to control which features are available per report. Valid options are;
'P' -- Prevent Printing.
'E' -- Prevent Emailing.
'S' -- Prevent Saving (or Emailing).
'F' -- Prevent Saving As (or Emailing) a PDF.
'X' -- Prevent Saving As (or Emailing) an Excel File.
'W' -- Prevent Saving As (or Emailing) a Word File.
'C' -- Prevent Uploading to any Drive
'G' -- Prevent Uploading to Google Drive
'O' -- Prevent Uploading to Microsoft OneDrive
'B' -- Prevent Uploading to DropBox
DropboxFolder String The default folder to store this report, if the report is uploaded to Dropbox.
EmailSignature String Used by the Email Templates.
EmailSubject String The subject line of the email when sending by email. If blank the the ReportName field is used as the subject.
EmailSynopsis String Used by the Email Templates.
EmailTemplate String The file name of the Email Template to use for the text portion of the email for this report.
EmailTemplateHTML String The file name of the Email Template to use for the html portion of the email for this report.
EmailText StringTheory The content to use for the text part of the email. If this property is set (even to a blank StringTheory object) then this will override the EmailTemplate field. The same tags as used in the email template can be used in this string.
EmailTextHTML StringTheory The content to use for the HTML part of the email. If this property is set (even to a blank StringTheory object) then this will override the EmailTemplateHTML field. The same tags as used in the email template can be used in this string.
EmailTo String A semi-colon separated list of email addresses. When the user clicks on the Email button this will provide the default email address for the report and the user can change or replace it.
If HideWindow is true, or PreventEmailChange is true then the user will not be able to override this setting.
ExcelFileName String The name of the Excel file to create when sending an email, or when saving as Excel. If Hidewindow is false then this is the default name used when the user clicks on the Save-As-Excel button.
ExcelOpenPassword String A password to apply to the created Excel file. Users will need to enter this password in order to open the spreadsheet in Excel.
ExcelEditPassword String A password to apply to the created Excel file. Users will need to enter this password in order to edit the spreadsheet in Excel.
GoogleDriveFolder String The default folder to store this report, if the report is uploaded to GoogleDrive.
HideWindow Long If this property is true then the preview window, will not be displayed to the user. If this is true then the Automatic field is also treaded as on. The other properties in the group (Destination etc) will instruct the Preview window what to do, and then the window will close automatically.
OneDriveFolder String The default folder to store this report, if the report is uploaded to Microsoft OneDrive.
OpenDocument Long If this property is true, and the user creates a Word, Excel or PDF document, then the document will automatically be opened after it has been created.
PDFFileName String The name of the PDF file to create when sending an email, or when saving as a PDF. If Hidewindow is false then this is the default name used when the user clicks on the Save-As-PDF button.
PDFOwnerPassword String Sets the owner password for the created PDF.  (Extended to all engines)
PDFPermissions Long Sets the user permissions for the PDF. (Extended to all engines)
The permissions should be some combination of
pv:AllowPrint, pv:AllowChange, pv:AllowCopy, pv:AllowForms (permissions can be added together.)
since each engine uses different equates for these values, the pv: values should be used - these are translated into the appropriate values for the engine being used.
PDFUserPassword String Sets the user password for the created PDF. (Extended to all engines). The user password will need to be entered by the user before the PDF file can be opened in a viewer. This password causes the file to be encrypted.
PreventEmailChange Long If true then the user cannot change the EmailTo when clicking on the Send Email button. If this is true, and the EmailTo field is not set then the user will not be able to send emails.
PreventFilenameChange Long If true then the user cannot change the Filename when clicking on the SaveAs button. If this is true, and the filename is not set, then the user will not be able to save files.
RecipientName String Used by the Email Templates.
Report &Report A pointer to the original report structure. This is used by some of the Export tools when exporting the report to other formats.
ReportName String The name of the report.
Used in the email text when the report is being sent via email.
Used as the Subject line of the email if EmailSubject is not set.
ReportDescription String Used in the email text when the report is being sent via email.
ReturnIfEmailWasSent Long not currently used
UserData StringTheory Data which can be set in the report procedure, which will be passed to the Premiere procedure, and from there to the SendEmail[1] and UploadFileToCloud[1] procedures. For more information see The UserData Field.

[1] The parameter will only be sent to these procedures if you are using NetTalk 12 (or no NetTalk at all).
WordFileName String The name of the Word file to create when sending an email, or when saving as Word. If Hidewindow is false then this is the default name used when the user clicks on the Save-As-Word button.
WordOpenPassword String A password to apply to the created Word file. Users will need to enter this password in order to open the spreadsheet in Word.
WordEditPassword String A password to apply to the created Word file. Users will need to enter this password in order to open the spreadsheet in Word.

Setting a Parameter

The template supports setting some of the parameters, but not all of them. If you wish to set a parameter which is not offered by the template, then you can do it in the embed code for the report.
The code will go into the Previewer.Display method, before the call to Premiere().

For example;

Previewer.Display PROCEDURE(...
 ReturnValue BYTE,AUTO
  CODE
  ! CapeSoft Premiere
  Clear(PreviewParms)
  PreviewParms.ReportName = 'Customer List Report'
  PreviewParms.EmailTemplate = 'CustomerReportEmailTemplate.Txt'
  PreviewParms.EmailTemplateHTML = 'CustomerReportEmailTemplate.Htm'
  PreviewParms.PDFFileName = 'Customer List.PDF'
  ! Start of "Set Premiere Options"
  PreviewParms.EmailSubject = 'Premiere Example Report via Email'
  ! End of "Set Premiere Options"
  ReturnValue = Premiere(self.ImageQueue,Report,PreviewParms)


The UserData Field

The UserData field in the Options Group allows the programmer to pass custom information from the report procedure, to the Premiere procedure, and from there into the SendEmail[1] and UploadFileToCloud[1] procedures.

The field is declared as a reference to a StringTheory object. In other words, it can be assigned to an existing StringTheory object. In the destination procedures it can be accessed as a StringTheory object, and any changes to the object will change the original object in the Report procedure. In this way results can all be passed back to the report procedure.

To use this property instantiate (create) a StringTheory object in the report procedure. This could be declared in the data pad, or in embed code. For example;

UserData StringTheory

It can then be assigned to the group using the reference assignment. (There is also a template setting you can use for this.)

PreviewParms.UserData &= UserData

The contents of the object are up to you, and can be anything you like. If you have a single item to pass you might just put it in there. If you have multiple items you could add them as a comma delimited list (or something like that.) As long as the "other end" knows what is in the field you can use it.

If you plan to make extensive use of this field then you could (and probably should) use a more structured approach, populating the field with JSON, or XML, or some other structured text format.

Note 1 : The parameter will only be sent to the SendEmail and UploadFileToCloud procedures if you are using NetTalk 12 (or no NetTalk at all).

Constructing a SendEmail procedure without NetTalk

The SendEmail() procedure is deliberately architected as a separate procedure in your application. This allows you to substitute an alternate method for sending emails - ie not using NetTalk.

The requirements for the procedure are as follows;

The Prototype for the procedure needs to be;
(EmailParametersGroup pEmail),Long,Proc
The parameters for the procedure needs to be
(EmailParametersGroup pEmail)

This group is declared for you in Premiere.Inc, and you can inspect the components for it there.
The following items in the group are populated by the Premiere window;
pEmailFileList
pEmailSubject
pEmailMessageText
pEmailMessageHtml
pEmailTo

Additional properties may also be set (in embed code) in the Premiere procedure, SendEmail method.

Constructing an UploadFileToCloud procedure without NetTalk

The UploadFileToCloud() procedure is deliberately architected as a separate procedure in your application. This allows you to substitute an alternate method for uploading - ie not using NetTalk or FileExplorer.

The requirements for the procedure are as follows;

The Prototype for the procedure needs to be;
(CloudParametersGroup pParms),Long,Proc
The parameters for the procedure needs to be
(CloudParametersGroup pParms)

This group is declared for you in Premiere.Inc, and you can inspect the components for it there.
The following items in the group are populated by the Premiere window;
pServiceName
pLocalFileName
pAutoStartUpload

Using NetTalk 7 / 8 / 9 / 10 / 11 / 12.29 (or earlier)

Email

The SendEmail procedure in the examples makes use of fields added with NetTalk 12.30. If you are using an older NetTalk (any level) then edit Netall.Inc to update the EmailParametersGroup so it appears as follows;

EmailParametersGroup Group,Type
pEmailFrom             String(255)
pEmailTo               String(255)
pEmailSubject          String(255)
pEmailCC               String(255)
pEmailBcc              String(255)
pEmailFileList         String(NET:StdEmailListSize)
pEmailEmbedList        String(NET:StdEmailListSize)
pEmailMessageText      String(100000)
pEmailMessageHtml      String(100000)
pEmailSettingsPath     String(255)
pEmailTest             Long
pHelo                  String(255)  ! 8.11
pSSL                   Long         ! 8.11
pStartTLS              LONG         ! 8.11
pSign                  Long         ! 9.00
pHide                  Long         ! 9.02
pServer                string(255)  ! 9.08
pPort                  Long         ! 9.08
pEmailReplyTo          string(255)  ! 9.08
pSmtpUser              String(255)  ! 9.12
pPassword              String(255)  ! 9.12
pSSLMethod             Long         ! 9.17
pEmailFileNameList String(NET:StdEmailListSize) ! 10.20
pEmailImagePath String(255)                     ! 11.24
pUserData &StringTheory                         ! 12.30
                     End

This update will not affect NetTalk 7,8,9,10 or 11 in any way.

Cloud Drive

 The UploadFileToCloud procedure in the examples makes use of fields added with NetTalk 12.30. If you are using an older NetTalk (any level) then edit Netall.Inc to update the CloudParametersGroup so it appears as below. If you are using a version of NetTalk older than NetTalk 10 then the Cloud Upload feature is not available to you.

CloudParametersGroup    Group,type
pServiceName              string(20)
pLocalFileName            string(256)
pCloudFileName            string(256)
pClientId                 String(256)
pClientSecret             String(256)
pAutoStartUpload          Long
pUserData                 &StringTheory   ! 12.30
                        End

Email Templates

When sending reports via email it is often useful to have the email text formatted a specific way to make the email attractive to the recipient. It is also occasionally desirable to use different email text for different reports.

In order to allow for this, Premiere supports the concept of Email Templates. These are text files which can be created by the developer, and, if necessary, customized by the end user.

Email Tags

Special "tags" inside email text and HTML allow text replaced when the email is created. These tags work regardless of the email source (ie the EmailTemplate, or the EmailText properties)

Supported tags are
[clock] The current time
[recipientname] The corresponding value in the  PremierePreviewOptions.
[reportdescription] The corresponding value in the  PremierePreviewOptions.
[reportname] The corresponding value in the  PremierePreviewOptions.
[signature] The EmailSignature value in the  PremierePreviewOptions.
[synopsis] The EmailSynopsis value in the  PremierePreviewOptions.
[time] see [clock]
[today] The current date, formatted with @D4 picture.

HTML in Emails

HTML in Emails is not the same as HTML in a browser. For more information on this see the NetTalk docs at https://www.capesoft.com/docs/NetTalk9/NetTalkEmail.Htm#ConstructingHTML

Template Settings

Each report can make use of different email templates. The Report Extension Template has settings which allow you to set templates for both the HTML and Text part of the emails.

Some Online Tools for creating HTML Templates

Goggling for online tools to help with creating email templates quickly leads you to many possible options. Some suggested sites are;

NetTalk Version

If you are using NetTalk version 9.20 or later then (local) image references in the template will automatically be embedded into the email. For example if your email template contains something like;

<img src="capesoft200.png">

Then this image will be embedded in the email.

Automation

The PremierPreviewOptions Group contains a number of options that let you completely, or partially, automate the preview window.

Default File Names and Locations

You can control, or suggest, the name for PDF, Excel or Word files in different places. This section discusses those places in order of most specific to least specific.

Bear in mind that any file name consists of two parts, the name of the file and the location (full path) to the file. With some thought it's possible to set these separately in different places, as discussed below.

Report Procedure

The most specific place is in the report procedure itself. In the Premiere extension to the report you can set individualized names, and possibly paths for the PDF, Excel and Word files. This could be a fixed value or an expression.
This value defaults to the procedure name with the appropriate extension.

There is also a setting here (Prevent File Name Change) which, if set on, prevents the user from changing the name (or location) of the file.

In addition you can set the default cloud directories here for the supported cloud drives.

Premiere Procedure

If the PATH is not set in the report procedure, then the Premiere (preview) procedure can default the location of the file to a specific folder. this is set via the Default File Folder setting, on the Premiere Extension, on the Defaults Tab. You can choose from a number of common windows folders (Desktop, My Documents etc), use the Current Folder, or specify some other specific folder there.

On the Defaults Tab you can also set the default directories to use for the various supported Cloud drives.

At Runtime

If the Cloud path is not set by the report, or the Premiere procedure, then the last-used folder will be suggested to the user.
the user is able to override the suggestion with another path if they choose to do so.

Translations

As the Premiere window is just a procedure in your application you are free to translate the text on the window (and generally change the window layout and design) as you please.

There are however some interface elements in the class - default text for emails, popup options on the Pages button, AdvancedPrint button and so on which you may wish to translate. A mechanism for this is provide by the .Translate method in the class.

All English text in the class is passed to the Translate method when it is used. You can then use your favorite translation tool to translate the text there. (Naturally, if you are using AnyText as your favorite tool, then  you don't need to do anything as Premiere supports AnyText automatically.)

To add your translation code, you can embed directly into the Translate method in the Premiere procedure. There is only one input, the text to be translated, and only one return value - the translated text.

Example;

ThisPremiere.Translate PROCEDURE (String pText)
ReturnValue any
  CODE
  ReturnValue = MyFavoriteTranslationTool(pText)
  Return ReturnValue


Fast Report Closing

Acknowledgement: This issue, and solution, was first proposed by Carl Barnes, and documented on ClarionHub and ClarionLive.

When a report is closed, then all the temporary files used by the report are deleted from the temp folder.This is done automatically by the CLOSE(Report) function.

Unfortunately this function (internally) makes use of the REMOVE command, which in turn has some option parameters, and hence it's designed for flexibility, not speed. The Windows API call (DeleteFileA) is less powerful, but at the same time much faster. For reports with a number of pages this speed difference is noticeable for reports of about 40 pages, and is significant for reports of around 100 pages or more. For very large reports (several hundred pages) the time taken to close the report is painful.

Premiere includes a function (PremiereDeleteFilesInPrintPreviewQueue), which can be added to report procedures, which deletes the files using DeleteFileA. This greatly improves the performance of the closing of the report (ie after the previewer closes). It is a simple function call, and does not require an object to be declared in the procedure. It takes the print preview queue as a single parameter.

ABC and Legacy App Report Procedures

By default if the report calls the Premiere previewer then the template will add a call to the PremiereDeleteFilesInPrintPreviewQueue function before the call to Close(Report). There is nothing to do, it is simply on.

This can be overridden at the global level, or the local level. You might wish to override the call if it would interfere with your own queue manipulation.

Hand-Code / Other Report Procedures

If you have a hand-coded report, and you wish to make use of this function then simply call

PremiereDeleteFilesInPrintPreviewQueue(PrintPreviewQueue)

Before the call to CLOSE(Report)

Password Protected PDF, Excel and Word Files

Premiere can create PDF, Excel and Word files from the report. It can also Email or Upload these files after creation. It is sometimes desirable to password-protect these files because they may contain sensitive or private information. Premiere allows the user to optionally enter a password when setting the file name, which will in turn cause the file to be protected with the password.

This feature is new in build 3.37. If you have used a version prior to this version in your application then you will need to tweak your PremiereGetData procedure. See Upgrading Premiere for more information.

This feature makes use of Office Inside build 4.68 (for creating the Excel and Word files). So to support these files you will need to be on Office Inside 4.68 or later.

FAQ

  1. Why are PDF files created with the SV PDF Engine very large?

Why are PDF files created with the SV PDF Engine very large?

The SV PDF Engine can generate files using one of two modes. Scan Copy Mode makes bigger files, but supports more non-ASCII character sets. You can set the engine to use Scan Copy mode, or not, in the  Premiere Extension template in the PremiereCreatePDFFromQueue procedure which is in your app tree.

Note that PDF's in Scan Copy mode do not support password protection.

Template Reference

Global Extension Template Extension

Options Tab

Preview Procedure
Select the name of the Preview Procedure here. The default is Premiere, and if this setting is left blank then this name will be used.
Generate External Premiere Procedure into Map
If this is a Multi-DLL system, and this is NOT the Data DLL, then the Premiere function will be added to the MAP for you and you do not need to have it declared in your application tree. If you do want it declared in the tree (as an external) then tick this option off to avoid Duplicate Identifier errors.
Use PDF Engine
If set to "default" then the PDF engine included in your app will be detected and used. If you wish to override the auto-detection then you can do so here. You can also choose to suppress PDF support (even if an engine exists) here.
Use Office Engine
If set to "default" then the Office engine included in your app will be detected and used. If you wish to override the auto-detection then you can do so here. You can also choose to suppress Office support (even if an engine exists) here.
Use Email Engine
If set to "default" then the Email engine included in your app will be detected and used. If you wish to override the auto-detection then you can do so here. You can also choose to suppress Email support (even if an engine exists) here.
Use Cloud Engine
If set to "default" then the Cloud engine included in your app will be detected and used. If you wish to override the auto-detection then you can do so here. You can also choose to suppress Email support (even if an engine exists) here.

Defaults Tab

The settings on this tab are defaults for local report options. These options can be overridden at the local procedure level.
Show Preview Window
If this expression resolves to true, then the preview window will be visible after the user generates the report.
Default Destination
If the preview window is not visible, then the output will go directly to this destination. Some destinations require specific tools. See the PremierePreviewOptionsGroup for more details.
Expression
If the above setting is set to Expression, then this option will be available. You can then enter an expression which contains the desired destination value.
Auto Open Document
If this is set to true, and the user saves the report to a PDF, Excel or Word document, then the document will automatically open in the respective program once it has been generated. This option does not require Hyperactive.
Email Signature
A default email signature can be set here. This will be added to the bottom of the default email text, and will also be injected into template, or StringTheory, email text replacing the [emailsignature] tag.

Multi DLL Tab

This is part of a Multi-DLL program
If this app is part of a suite of apps, where you are making your own DLL's, then tick this option on in all the apps, including the DLL apps and the EXE apps in the suite.
Export Premiere Class from this DLL
Check this box if this app is the root DLL of the app suite.

Report Extension Template

General Tab

Disable This Extension
If this switch is on the no code will be generated into this procedure by the Premiere template.
Preview Procedure
Leave this blank to use the global preview procedure. Or enter a specific procedure for this report here.
Show Preview Window
If this option is blank then the global default will be used. If the global default is also blank then this option defaults to true (ie the preview window will be displayed.) If this option (or the global option) is set, and evaluates to false, then the preview window is not visible to the user after the report runs. In this situation the Auto Open Document, Default Destination and various file name settings will be important, and will determine the behavior.
Auto Open Document
If this option is blank then the global default will be used. If the global default is also blank then this option defaults to false (ie the document will be created, but not automatically opened. If Hyperactive is in the app then the user will have the option to open the file manually.)
Automatic
If this option is blank then it defaults to false. If this option evaluates to true then the previewer will automatically perform the task, as determined by the Destination field (Print, make a File, Email etc.)
Report Name
Used as the Subject when emailing the report. Also used in the message body of the email.
Report Description
Used in the message text when sending an email to a user.
Default Destination
If set to Default (or nothing) then the global template option will be used. If the preview window is not visible, then the output will go directly to this destination. Some destinations require specific tools. See the PremierePreviewOptionsGroup for more details. 
PDF File Name
The default name to use when a PDF file is created by the previewer. The user will still be asked for the name, but the default name will be presented to them. This field is an expression, meaning that current date and time (or anything else) can be included in the name.  For example;
'Customer Report as at ' & format(today,@d1)
Excel File Name
As for the PDF Filename above, but used when exporting to Excel.
Word File Name
As for the PDF Filename above, but used when exporting to Word.
Prevent File Name Change
If this is on then the user will not be able to change the generated file names. The names set above will be used.
Fast Delete WMF Files
If this is set to Yes (or Default, with the global setting set to Yes), then Premiere will delete the WMF files itself before returning control to the Report procedure. Premiere bypasses an issue in Clarion where deleting files can be slow for large numbers of files. Unless you are doing further manipulation of the WMF files in the report procedure, After the previewer, this option can be set to Yes.
User Data (st Object)
The label of a StringTheory object can be entered here. This field should JUST be the label of the object. You can select from the data pad, or simply type the name of the object in here.

Disable Tab

This tab lets you disable features in the previewer on a report-by-report basis. For example some reports may not be suitable for savig to Excel, and so this can be turned off for that report.

Email Tab

Email To
The default address to send the report to, if the user selects the Email button. The user will still be able to change the email address. Note that this field is an expression, so a user-related value might be appropriate.
Prevent Email Address Change
If this is on the the user will not be able to override the email destination of this report. In other words the report can only be emailed to the specified address above.
Email Subject
A subject line to use when emailing. If this is left blank then the report name is used in the subject line of the email.
Email Text Content (st)
The label of a StringTheory object, containing the content of the email text part to send with this report. If this is set then the Email Template (Text) setting is ignored. Email tags can be used.
Email HTML Content (st)
The label of a StringTheory object, containing the content of the email HTML part to send with this report. If this is set then the Email Template (HTML) setting is ignored. Email tags can be used.
Email Template (Text)
The name of the email template to use for the text potion of the email body.
Email Template (HTML)
The name of the email template to use for the html potion of the email body.
Email Signature
A signature to replace the [emailsignature] tag. This signature will also be appended to the standard email text if no text, or template, is set.
Email Synopsis
Text to replace the [emailsynopsis] tag. This synopsis will also start the standard email text if no text, or template, is set.

Previewer Control Template

Options Tab

Selected Page Color
Not currently Used.
Unselected Page Color
Not currently Used.
Allow Send Email from Previewer
If this option is off then the Email button on the previewer will be disabled. If this option is on then you will need a SendEmail procedure in the application.
SendEmail procedure
This is the procedure that will send the email. If this option is blank, and the option above is ticked, then the default name SendEmail will be used.
Allow Save To Word from Previewer
If an Office Engine is set, then you can use this option to prevent exporting to Word. If there is no Office engine set then this setting has no effect.
Allow Save To Excel from Previewer
If an Office Engine is set, then you can use this option to prevent exporting to Excel. If there is no Office engine set then this setting has no effect.
Allow File Upload from Previewer
If this option is off then the Upload button on the previewer will be disabled. If this option is on then you will need a UploadFileToCloud procedure in the application.
Upload procedure
This is the procedure that will upload the file to the cloud. If this option is blank, and the option above is ticked, then the default name UploadFileToCloud will be used.
Allow Commas in FileNames.
By default Premiere does not allow commas in export to (PDF, Excel etc) file names. This is because NetTalk 10 (and earlier) did not allow commas in the attachment list when sending emails. In NetTalk 11 and later commas are allowed. If you are using NetTalk 10 or earlier, leave this option set to false. If you are using NetTalk 11 or later (or some other email engine that does support commas) then you can turn this option on.

Defaults Tab

Default File Folder
Use this to set the default location for created PDF, Excel and Word files.
Folder
If the Default File Folder is set to Specific folder then you can enter an expression for the specific folder here.
Default Folder For
This lets you set the default folder for the listed cloud services. If the user saves a report to the cloud then this will be the folder suggested to them.

CreatePDFFromQueueControl Template

General Tab

Disable This Extension
If this switch is on the no code will be generated into this procedure by the Premiere template.

SV PDF Tab

Show Progress
If on then a progress window is displayed when converting the report to a PDF.
Use Scan Copy Mode
Turns on the ScanCopyMode feature for the SV PDF engine. This is most useful when using non-ASCII character sets. If this is on then the PDF files will be much larger than when it is off.

wPDF Tab

Compression
Set the compression level for the wPDF engine.
JPEG Compression
Set the JPEG compression level for the wPDF engine.
Font Mode
Set the Font mode for the wPDF engine.

CreateOfficeFromQueueControl Template

This template is used in the PremiereCreateExcelFromQueue and PremiereCreateWordFromQueue procedures.

General Tab

Format
Select from Excel or Word.
Disable This Extension
If this switch is on the no code will be generated into this procedure by the Premiere template.

GetData Control Template

General Tab

Disable This Extension
If this switch is on the no code will be generated into this procedure by the Premiere template.
Lookup Dialog Header
Allows you to change the wording used by the FileDialog command when the user does a file lookup.

Examples

There are 8 examples that ship with Premiere.

ABC All

This is the full-featured example and includes Premiere, NetTalk (for emailing and cloud), FileExplorer for cloud upload, Office Inside for Excel and Word support, Hyperactive and the SV PDF Engine. The PDF engine can be replaced with whichever PDF engine you prefer. If you have File Explorer, Office and NetTalk then this is the recommended example to use.

If you use this example as a source for your own application then note the two tables in the dictionary (EmailLog and EmailSettings) which you will likely want to import into your dictionary as well.

Legacy All

A Clarion (Legacy) version of the ABC All example.

The resize template on the Premiere procedure is the built-in Clarion Legacy Resize template. It is recommended that this be replaced with a more capable resizing template, such as ResizeAndSplit.

ABC Office

This example includes Premiere, Office Inside Hyperactive and the SV PDF Engine. The PDF engine can be replaced with whichever PDF engine you prefer. Use this example if you have Office Inside, but not NetTalk.

Legacy Office

A Clarion (Legacy) version of the ABC Office example.

The resize template on the Premiere procedure is the built-in Clarion Legacy Resize template. It is recommended that this be replaced with a more capable resizing template, such as ResizeAndSplit.

ABC NetTalk

This example includes Premiere, NetTalk (for emailing), Hyperactive and the SV PDF Engine. The PDF engine can be replaced with whichever PDF engine you prefer. If you have NetTalk, but not Office  then this is the recommended example to use.

If you use this example as a source for your own application then note the two tables in the dictionary (EmailLog and EmailSettings) which you will likely want to import into your dictionary as well.

Legacy NetTalk

A Clarion (Legacy) version of the ABC NetTalk example.

The resize template on the Premiere procedure is the built-in Clarion Legacy Resize template. It is recommended that this be replaced with a more capable resizing template, such as ResizeAndSplit.

ABC

A minimal ABC app with the Premiere report preview, but no PDF engine, no Office engine and no Email engine. You can add your favorite PDF engine to this app to enable the Save As PDF button.

Legacy

A minimal Clarion (Legacy) app with the Premiere report preview, but no PDF engine, no Office engine and no Email engine. You can add your favorite PDF engine to this app to enable the Save As PDF button.

The resize template on the Premiere procedure is the built-in Clarion Legacy Resize template. It is recommended that this be replaced with a more capable resizing template, such as ResizeAndSplit.

Multi-DLL ABC

A Multi-DLL ABC app with the Premiere report preview, and SoftVelocity PDF engine (in the Data DLL) a report (no PDF engine) in the Functions app, and nothing in the Demo app.

You can remove the SV PDF extension and replace it with the global extension for PDF-Tools or wPDF templates if you like.

Multi-DLL Legacy

A Multi-DLL Clarion (Legacy) app with the Premiere report preview, and SoftVelocity PDF engine (in the Data DLL) a
report (no PDF engine) in the Functions app, and nothing in the Demo app.

You can remove the SV PDF extension and replace it with the global extension for PDF-Tools or wPDF templates if you like.

The resize template on the Premiere procedure is the built-in Clarion Legacy Resize template. It is recommended that this be replaced with a more capable resizing template, such as ResizeAndSplit..

Errors

  1. GEN: Unknown Template type HyperActive(HyperActive)
    Unknown Variable %HaDefaultBright
    Errors when Importing from a TXA. See Note [3].
  2. Prototype is: PREMIEREGETDATA(STRING,*STRING,STRING) - C:\ABS
    Unknown identifier: PWHAT

    Likely occurs just after the TXA import of the procedures. See [2] for more information. Just going to the Properties of each Premiere Procedure  solves the problem.
  3. No Matching Prototype Available
    When you are not using Email. See Note [4].
  4. No matching prototype available on
    Return UploadFileToCloud(pCloud)
    When you are not using Cloud support. See upgrading.

Support

Your questions, comments and suggestions are welcome. Check our web page (www.capesoft.com) for new versions. You can also contact us in one of the following ways:

CapeSoft Support
Support Page Find support page with various options here
Email support@capesoft.com
Telephone (landline) +27 87 828 0123 (outside South Africa)
087 828 0123 (inside South Africa)

Distribution

No additional files are required for shipping.

License & Copyright

This template is copyright 2023 by CapeSoft Software. None of the included files may be distributed. Your programs which use Premiere can be distributed without any royalties.

This product is provided as-is. Use it entirely at your own risk. Use of this product implies your acceptance of this, along with the recognition of the copyright stated above. In no way will CapeSoft Software, their employees or affiliates be liable in any way for any damages or losses you may incur as a direct or indirect result of using this product.

Version History

Version 3.48 - 14 April 2023
 Version 3.47 - 18 July 2022
 Version 3.46 - 7 February 2022
 Version 3.45 - 2 February 2022
 Version 3.44 - 31 January 2022
 Version 3.43 - 6 December 2021
 Version 3.42 - 10 November 2021
Version 3.41 - 28 October 2021
 Version 3.40 - 17 October 2021
 Version 3.36 - 23 September 2021
 Version 3.35 - 17 August 2021
 Version 3.34 - 24 May 2021
 Version 3.33 - 22 September 2020   Version 3.32 - 4 September 2020   Version 3.31 - 7 August 2020   Version 3.30 - 28 June 2020   Version 3.29 - 21 October 2019   Version 3.28 - 23 July 2019   Version 3.27 - 1 October 2018   Version 3.26 - 14 September 2018   Version 3.25 - 30 August 2018   Version 3.24 - 22 August 2018   Version 3.23 - 15 August 2018   Version 3.22 - 26 July 2018   Version 3.21 - 15 May 2018   Version 3.20 - 2 May 2018   Version 3.12 - 9 February 2018   Version 3.11 - 9 January 2018   Version 3.10 - 3 January 2018   Version 3.08 - 24 November 2017   Version 3.07 - 17 November 2017 -- SEE upgrade notes for changes to your program Version 3.06 - 21 February 2017 Version 3.05 - 20 February 2017 Version 3.04 - 17 February 2017 Version 3.03 - 19 December 2016 Version 3.02 - 22 November 2016 Version 3.01 - 21 November 2016 Version 3.00 - 18 November 2016 Version 1.00 - 17 September 2007