There is a completed example, in which all of the below steps have been followed, in your clarionx\3rdparty\examples\RightReports\abc folder.

Step  1: Install the latest versions of Draw, RightReports and Clarion FreeImage.

• Note that you need Draw version 2.53 or later for RightReports to work.
• Note that besides running the FreeImage install file,  you will also need to download the FreeImage DLL (http://www.clarionfreeimage.com/) and put this in your clarionx\3rdparty\bin directory.
• Make sure that you pick the option to register the template for each of the three installs, if they are not already registered.
• Note: There are two templates to be registered by the installer. The first is RightReports.tpl, and the second is editin.tpl. In some cases registration of the latter fails. If it does, you will get an "Unknown Template Type (EditInPlace) " type error when trying to open one of the example apps, or an app with the RightReportsUpdate procedure in it. To fix this, go to "Template Registry" under the Setup Menu and register editin.tpl in clarionx\3rdparty\template.

Note: You can get by without Clarion FreeImage, but it does very much limit the type of image files you will be able to use in your reports. In fact, you will only be able to use bitmaps.

Step  2: Import the RightReports Tables into your dictionary.

• Open your dictionary in the Clarion IDE. 
• Choose File|Import Text.
• Go to your Clarionx\3rdparty\Libsrc folder.
• Choose the RightReportsTables.txd file (or RightReportsTablesSQL.txd) and Open it.
• Make sure you change the file drivers for the imported files (they all start with RR) to the one you are using.
• If you are using an SQL backend, dont forget to fill in the Owner for each imported table (except RRImportASCII).
• If you are using FM3 or FM2, dont forget to add the Version option (set to 1) under the Table Options for each imported table.
• Save and close your dictionary.

Step 3: Import the RightReports Procedures into your app.

• Open your application in the Clarion IDE. If this is a Multi-DLL application, then open your reporting DLL
• Go to File|Import Text ...
• Import the RightReportsFunctionsABC.txa or RightReportsFunctionsLegacy.txa file in your clarionx\3rdparty\libsrc folder (if your application is Multi-DLL, import this into your reporting DLL).
• See the section on Imported RightReports Procedures for more info on the imported procedures.
• If you have xFiles added to this application, then you can import the Import and Export procedures into your application - by importing the RRImportExport.txa file (as per the above 3 steps).

Step 4: Add the FreeImage, Draw and RightReports global extensions to your Single EXE app (see Step 4a for Multi-DLL).

• Open your application in the Clarion IDE.
• Click on the Global button.
• In the Global Properties window, click on the Extensions button.
• Click on the Insert button and select the Activate_ClarionFreeImage extension template.
• Click on the Insert button and select the GloDraw extension template.
• On the Options Tab of the Draw Global Template, tick the “Activate DrawImage” and “Activate DrawPaint” options.
• Click on the Insert button and select the Activate_RightReports (Activate RightReports Functions) extension template.
• If you want to be able to export reports to a Microsoft Word or Excel document, add the CapeSoft Office Inside global extension.
• If you want to be able to preview PDF files (providing you have Clarion EE or abprpdf.inc/clw), add the Hyperactive global extension. Make sure you add the local extension to the RightReportsPrint procedure too.
• Click OK and OK again.

Step  4a: Multi-DLL Applications

If you have a multi-DLL application and have added Draw to your Data DLL, the way to add the global Extensions is as follows:

• Add the Draw Global Extension to the Data DLL, and on the General Tab, tick the “Activate DrawImage” and “Activate DrawPaint” options.
• Add the Global Clarion FreeImage Extension to the Data DLL, too
• Add the Draw Global Extension to your reporting DLL, and on the General Tab, tick the “Activate DrawImage”,  “Activate DrawPaint” and "Use Draw that is exported in another DLL" options.
• Add the Global Clarion FreeImage Extension to your reporting DLL
• Add the Global RightReports Extension to your reporting DLL
• Make sure Generate All File Declarations (Global Properties | File Control Tab) is ticked in your Data DLL
• If you want to be able to export reports to a Microsoft Word or Excel document, add the CapeSoft Office Inside globa extension to the reporting DLL.
• If you want to be able to preview PDF files (providing you have Clarion EE or abprpdf.inc/clw), add the Hyperactive global extension to the reporting DLL. Make sure you add the local extension to the RightReportsPrint procedure too.

Step 5: Tick the Generate All File Declarations option for your app.

You can find this by clicking on the Global button and going to the File Control tab – it’s the first checkbox. If you don’t do this, RightReports will only pick up tables you’ve specified in the table tree structures of the procedures in your application, and you will hence be able to use only these tables in your reports at runtime. Ticking this option ensures that RightReports makes all the tables in your dictionary available to the end user.

Step 6: Fill in some of the Global Template Options.

There are three main things you probably want to worry about here:

• Adding extra data sources and relationships to be used for reporting purposes (besides the files in your dictionary, which are added automatically)
• Specifying which Previewer to use
• Specifying any custom functions you wish to make available to users in reports (see also the Functions Tab in the Editor)

Step 7: Call the RightReportsBrowse procedure from somewhere in your app.

This is a browse for all the reports that have been created in your program. Make sure you call the RightReportsBrowse procedure with parameter 0 for now, i.e. call RightReportsBrowse(0). If your application has a Frame, adding a Browse Reports option to one of the menus might be an idea.

Step 8: Ok … Go!

Compile and run your app - and take a look at the Using the Report Editor section of this doc for details on creating reports.

You will notice that one of the steps explained above while adding RightReports to your application involved importing a number of procedures. Below we give a short description for each of these procedures.

• RightReportsBrowse: This is the browse containing all the reports created in your application.
• RightReportsUpdate: This is the Report Editor. Its the window that pops up when you choose to edit a report in the browse above, and is actually a form that updates the report tables.
• RightReportsOverrideParentFile: This is a window that will pop up when you choose the edit the parent file of a Secondary Loop or Lookup.
• RightReportsPremier: This is the built-in RightReports report previewer.
• RightReportsPrint: RightReportsPrint is the procedure responsible for printing the report created by the report editor. There is a special section on RightReportsPrint giving more information.
• RightReportsViewTextFile: This is the built-in RightReports report previewer for text reports.
• RightReportsImportTXR: This imports the specified TXR file into RightReports. Users can then edit and print the imported reports as usual. See also the section on Importing and Exporting Reports.
• RightReportsExport: This exports the specified report to an xml file. Users can the use the below procedure to import the report. This is useful for making reports mobile - for example, you could design the report on your end and then just email the exported xml file to a client, who can then import the report again. See also the section on Importing and Exporting Reports.
• RightReportsImport: This imports a report from a specified xml file. See RightReportsImport above for more details. See also the section on Importing and Exporting Reports.

The Global Extension

The General Tab

• Disable All RightReports Features: Use this for debugging.
• Enable Web Server in PrintReport: If you have added NetTalk 4 to your application and want to be able to use RightReports with your web server, tick this option. Not fully supported yet.
• Enable Printing to PDF: If you want RightReports to be able to output to a PDF file, tick this option. You need the abprpdf class files for this - if you have Clarion 6 Professional Edition, this is included.
• Use HyperActive to preview PDF Files: If you have HyperActive Installed and added to your application, you can tick this and PDF files will be previewed using HyperActive.
• Previewer: RightReports: Choose this option if you want the built-in RightReports Previewer to preview printed reports.
• Previewer: ABC: Choose this option if you want the built-in ABC Previewer to preview printed reports.
• Previewer: IceTips, RPM or CPCS: You can also choose to use other 3rdparty report previewers. Depending on your choice, a new Tab may appear with options for that previewer, as is discussed below. See the section on The Report Previewer for more details on how to use these options.

The Previewer Tab

Depending on your choice of Report Previewer, a tab may appear with options for that Previewer. These are basically the options for that previewer as they would appear if you had installed and used that 3rdparty tool directly. Consult the documentation that came with that tool for more information on the available options. See also The Report Previewer for more details on how to install and use these 3rdparty report previewers.

The Data Sources Tab

All tables in your dictionary will be included and made available to users according to the Files Tab. If you would like to make other data sources available to users, such as queues and views, you need to fill in the details here. The insert window looks similar to the following:

You are required to enter the Label of the data source, as well as a prefix (if it has one). For View's, you need to specify its primary source. For Queues, you will notice you can add Orders to the list provided. The idea is that you give each order a unique name and specify the fields in the queue to be used for this order.

Note that you can enter data sources here that are either declared globally (preferably threaded), or locally in the RightReportsPrint AND RightReportsUpdate procedures. The data sources need to be available to both of these procedures for the following reason: The Update procedure needs it in order to make it available to the user at run time. It needs the actual structure in order to add it to the list of data sources available to the user for report creation, to provide a list of fields, etc. There does not need to be data in the data source at this point. The print procedure, however, needs both the data structure as well as the data in order to print out the report.

We've placed this Tab on the global extension to prevent the need for you to enter this information twice (once for the update procedure, and once for the print procedure). Unfortunately this means that you have to type out the names of your data sources by hand, as global extensions do not allow you open the Fields Dialogue.

The Relationships Tab

Once you have entered your Queue and View data sources on the Data Sources Tab above, you can specify relationships for them on this here Relationships Tab. Since File relationships are determined by your dictionary structure, the idea is that you use this space to specify relationships between queues, or relationships between a queue and a file. The insert window looks like this:

You need to specify the data source and its relating source, the type of relationship, and also the orders (think of these as keys) used to establish the relationship. Once the latter has been filled in, you also need to specify how the fields of the specified keys are primed for this relationship, in the two Linking Fields boxes.

Note: If the list of files does not have anything in it, go out of the Global Extension, Generate All and go back in.

The Custom Functions Tab

On this tab, you can add functions defined in your procedure that you want to make available to users at run time (these will become available to them on the Functions Tab of the Editor). Users editing reports will be able to make use of these functions to calculate values, etc. to be included in the report.

You need to make sure you have created the function in your application before adding it to this list. Also, it needs to be accessible by the RightReportsPrint procedure. So it should either be declared as global, or added to the procedures for RightReportsPrint.

The Files Tab

On this tab you can override the fields you included or excluded from the Files List in your dictionary. This is useful for if you have more than one Report Editor in your application and you want to switch some of your tables on and off at DLL level rather than for the entire application.

• Suppress Files: Select the files that you don't want to appear in the report editor for this DLL.
• Include Files: Select files here that were excluded in the dictionary but you still want them to appear in the report editor for this DLL, Tree Defn File, Calcs File, Totals File, Secondary Source

The Advanced Tab

• Class is External: Tick this if you have a Multi-DLL application, and the Global Extension was added to a different DLL (i.e. if the RightReports class was compiled into a different DLL).
• Don't Link: Indicates that the class should not be linked in locally, it is external (in a DLL, not local).
• RightReports Based On: A super-advanced option allowing you to specify which class RightReports should inherit from.
• Tables per FQ module: For each table, a number of procedures are generated by RightReports. Originally, each table had its own module created by RightReports into which these procedures were generated. These modules are named something like repFQ1.clw, repFQ2.clw, etc. where "rep" is the first three letters of your application name. Since lots of tables hence means lots of FQ modules, you can specify here how many tables' procedures to generate into one FQ module to reduce this number. The default is 5.

The RightReports Files Tabs

You will notice that there are a number of other tabs on the Global Extension, such as Report, Band File, Controls File and Fields File. For the most, you will not need the tabs. If you, however, decide to rename some of the Imported RightReports Files or their fields, then you would possibly have to come to this tab to make sure all the table names, and their related field names, are still filled in correctly on this tab.

The Local Extension

The General Tab

• Disable Here: Use this to disable RightReports in this procedure. For debugging purposes, mainly.
• Show Ruler: You could have a ruler along the bottom of the graphic display area, if you wanted. Not fully implemented yet.
• Background Color: Set this to the colour you would like the background of the Graphic Band Editor to be.
• Gap Between Bands: Set this to the number of pixels you want to separate bands with in the Graphic Band Editor.
• Call Procedure to Update Control Properties: Usually you edit the properties of the selected control using the Property Tab. However, you could also add functionality to allow the user to edit these in a window via choosing an option from the right-click menu.
• Update Procedure: If the above option is ticked, enter the name of the update procedure for the control properties here.

The Hot Keys Tab

On this tab you can specify hot keys for editing and moving controls in the Graphic Band Editor. The prompts are rather self-explanatory.

The Advanced Tab

• Object Name: The name of the RightReports object in this procedure.
• Based on Class: A super-advanced option allowing you to specify which class RightReports should inherit from. By default it is whatever class was specified on the Global Advanced Tab. Once again its best if you leave this sucker alone.

The Browse Window

The RightReportsBrowse procedure lets you browse the current reports in your program.

It shows the date and time at which the report was last modified as well as the description. If you click the Add or Change button, you can edit this graphic report at runtime. The update procedure is called RightReportsUpdate.

The Update Form

The RightReportsUpdate procedure allows you to create and edit graphic reports with ease. There are three sections to this window:

• The Report Structure List on the left
• The Graphic Band Editor on the right
• The bottom left Property Sheet

The Report Structure List

This list allows you to specify a Primary Source, and add graphic report details, lookups, Secondary Source loops, calculations, headers and footers to your report. A short description for each of these is given below.

Note that you can move each item up or down depending on where on the report it should happen. You can also move each item left or right. If an item A is left of any item B above it, it means that that item B is a parent of item A.

• Primary Source: This specifies the Primary Source for the report.
• Lookup: If the current file has a many-to-one relation with another file, this can be used to look up the related record in that related file (by current file we mean the file of the closest parent that is either a Primary Source or secondary loop).
• Secondary Loop: If the current file has a one-to-many relation with another file, this can be used to loop through the related records in the related file.
• Calculation: Use this to perform a calculation and set a variable.
• Header: This is the header band for the report. There can be only one.
• Footer: This is the footer band for the report. Ditto re. the cheesy quote above.

The Graphic Band Editor

Any detail, header or footer created using the Report Structure List above appears in this editor. Check out the cool editing functionality available to you:

• Use the provided buttons to add boxes, strings, images and lines to any of the bands.
• Resize the bands and controls on the bands.
• Right-click and observe the neat popup menu allowing you to do things like align controls and copy-paste. Holding down the Control Key allows you to select multiple controls at once.

A note on Strings: Putting angular brackets around a word indicates to the report printing engine that this is possibly a local or global variable (see the Property Editor below), or a field in one of your report tables. See the Printing Variable and Field Values section for more details.

The Property Editor

This feature allows you to edit various properties belonging to the currently selected item in the Report Structure List. If a control is selected in the Graphic Band Editor, it allows you to edit the properties for that control. The property editor has several tabs:

• The Properties Tab: On this tab you can edit various properties for the selected item or control, including the text value, colors and position.
• The Totalling Tab (Only for Secondary Loops): You can create totals that are automatically calculated through the loop for the specified field.
  Note: The field has to be present somewhere on a band that has the loop as parent for the total to be calculated correctly.
• The Fields Tab: This just displays all the tables that are used in this report, with their fields and descriptions.
• The Functions Tab: This displays the functions available to the user. You have to create these yourself in your app, bind them in the BindRep procedure and add them to the AddCustomFunctions procedure (see the next step for more on this).
• The Global Tab: This is a list of global variables available to the user for use in the report. The user can edit, add and remove these at will. They are global in the sense that they are available to all reports in this program (see the next step for more on this).

• The Local Tab: Similar to the Global Tab, except that these variables are only available to the current report in the program.
• The Notes Tab: Write any general notes regarding the report here. There's lots of space, so go wild.

The Print Window

When you have finished editing the report, you can press OK to save it and then click Print on the Browse Reports window. This brings up the Report Options window (the procedure is called RightReportsPrint):

Here you can select where you want to print the file to, choose your printer, etc. Any local or global report variables which were declared of type “User” will appear on this window, allowing the user to specify their values.

You will also notice a Primary Sort dropdown appearing in some cases. This happens when for the Primary Source of that report, the user specified “User Selects” for the sort order. If the keys for the file have non-empty descriptions, the descriptions appear in this dropdown. Otherwise the key name appears.

Clicking start sends the printing on its way. See the section on The Report Output for more on the output options.

The Properties Tab on the Property Editor allows you to edit any of the properties relating to the currently selected item in the Report Structure List in edit-in-place type fashion. If a control on a band is selected, its properties will appear in the Property Editor for editing. Below we list the properties for each different type of item along with descriptions for each.

A Note on Parent Files

Recall we mentioned that if an item A is left of any item B above it in the Report Structure List, it means that that item B is a parent of item A. The idea of a parent file works more or less the same. The parent file of an item is assumed to be the main file of the closest Secondary Loop or Primary Source item above it. It is also possible to override the parent file of a given Secondary Loop or Lookup by changing the Parent File entry on the Properties Tab.

Primary Sources

This item contains properties relating to the Primary Source of the report, as well as other general

• Description: A description for the report. This description is what appears in the Browse Window.
• Primary Source: The name of the Primary Source through which this report will loop.
• Order By: Choose a key for the Primary Source by which it should ordered. If you have filled in a description for the key in the dictionary, this description will appear in the dropdown. Otherwise, the name of the key appears.
• Archive: To be updated.
• Order Fields: The fields in the key chosen in "Order By" above. To be updated.  
• Filter: Enter a report filter here for the Primary Source, if desired. This will be evaluated for every record fetched. You can include report variables in this expression.
• Server Filter: Enter a filter here. For files and views, this will be evaluated server side, which is quick, but means you cannot use any report variables.
• Server Order: Custom order fields for your data source. List of fields should be comma-separated. Evaluated server side. Only for files and views.
• SQL Filter: An SQL filter for your data source. Valid for files and views.
• SQL Order: SQL order fields for your data source. Valid for files and views.
• Format: Choose the format of the report. Options are Text, PDF, HTML, Excel, and XML. Some of these are To be updated.
• Graphic: Choose between Graphic and Text reports. This defaults to Graphic.
• Chain To: If you want another report to start printing immediately after this one has been printed, put the report number here.
• Report Number: The report number of this report. This field is not editable.
• Send To: Choose where you would like the report to printed to by default. Choose between Printer, File and Screen.
• Destination: Choose the printer you would like this report to be sent to by default.
• Landscape: Choose whether you want the report to be printed in landscape form by default.
• Report Type: The user can use this at his or her discretion. Useful for grouping different types of reports together.

Secondary Loops

• Parent File: If you would like this to have a differrent parent file than the default, choose it here. See the section on Secondary Loops and the Note on Parent Files to see what a parent file is.
• File Name: The name of the Secondary Source to loop through. Only files related to this item's parent file in a many to one relationship will appear in this dropdown.
• Cache: To be updated.
• Filter: A report filter for this Secondary Source. This will be evaluated for every record fetched. You can include report variables in this expression.
• Server Filter: Enter a filter here. For files and views, this will be evaluated server side, which is quick, but means you cannot use any report variables.
• Server Order: Custom order fields for your data source. Valid for files and views. List of fields should be comma-separated. Evaluated server side.
• SQL Filter: An sql filter for your data source. Valid for files and views.
• SQL Order: SQL order fields for your data srouce. Valid for files and views.
• Range _ From: There may appear a number of these prompts, depending on the key relating this Secondary Source to its parent files. If there are fields other than fields linking this Secondary Source to its parent file in the relating key, there will appear such a prompt for each of these fields. Fill in the range from value for this field, if desired.
• Range _ To: There may appear a number of these prompts, depending on the key relating this Secondary Source to its parent files. If there are fields other than fields linking this Secondary Source to its parent file in the relating key, there will appear such a prompt for each of these fields. Fill in the range to value for this field, if desired.

Lookups

• Parent Source: If you would like this to have a differrent parent file than the default, choose it here. See the section on Lookups and the Note on Parent Files to see what a parent file is.
• Source Name: The name of the file to do the lookup on. Only files related to this item's parent file in a one to many relationship will appear in this dropdown.
• Cache: To be updated.
• Linking Fields: This only appears if the Parent File is set to None. This allows you to do a lookup based on a custom relationship between files. What is required here is an expression that links up to three fields in the Lookup file to corresponding fields in the parent file.In other words, supposing the parent file is Invoice and the file to do the lookup on is Customers, it needs to have the following format:

CUS:CField1 = INV:IField1

or

CUS:CField1 = INV:IField1 and CUS:CField2 = INV:IField2

or

CUS:CField1 = INV:IField1 and CUS:CField2 = INV:IField2 and CUS:CField3 = INV:IField3

You also need to make sure that there is a key in the Lookup file that contains each of the lookup fields used in the expression. Otherwise, the lookup will not work.

Calculations

• Calc Name: The name of the calculation. You may call it whatever you like.
• If: A condition for the calculation. Set to 1 if no condition is required. If you are using any variables or table fields in this condition, they should be enclosed by angular brackets.
• Set: The name of the variable to receive the result of the calculation. This variable will have to be declared either on the Global Tab or the Local Tab. You may write the variable names as in, although putting angular brackets around it wont hurt.
• To: The calculation/expression you would like the variable above to be set to. Once again you may use table fields or variables, but remember to put angular brackets around them.
• Else Set: The name of a variable to set if the condition fails. This variable will have to be declared either on the Global Tab or the Local Tab. You may write the variable names as in, although putting angular brackets around it wont hurt.
• To: The value to set the Else Set variable above to. It can be an expression. Once again you may use table fields or variables, but remember to put angular brackets around them.

Details, Headers, Footers and Forms

• Detail/Header/Footer Name: A descriptive name for this band.
• Suppress If Block Empty: This is only valid for bands that appear between a Block Start and Block End statement. What this means is that this band should be printed only if other bands within the block that don't have this option ticked have been printed. A Suppressed detail is indicated in the Report Structure List by putting a star next to it. See the section on Blocks in a Report for more info.
• Block Start: This band is the start of a block. See the Suppress If Block Empty option above for more info. A Block Start is indicated in the Report Structure List by putting a closing angular bracket next to it. See the section on Blocks in a Report for more info.
• Block End: This band is the end of a block. See the Suppress If Block Empty option above for more info. A Block End is indicated in the Report Structure List by putting an opening angular bracket next to it. See the section on Blocks in a Report for more info.
• Hide: Don't ever print this band. But do execute calculations and evaluations relating to this band.
• Width: The width of this band on the report, in pixels.
• Height: The height of this band on the report, in pixels.
• Color: The background color of this band.
• Condition: A condition under which this band should be printed. May be an expression. You may use table fields or variables, but remember to put angular brackets around them. Can be left blank.

Controls

• Text: (String Controls Only) The text of the string control.
• X Pos: The vertical position of the control on the band, in pixels.
• Y Pos: The horizontal position of the control on the band, in pixels.
• Width: The width of the control on the band, in pixels.
• Height: The height of the control on the band, in pixels.
• Fit Width: If this is set, RightReports will adjust the size of the control to its contents when the report is printed, and the specified Width will be ignored. In particular, you can set this to ensure that a string control gets adjusted to the length of its contents when the report gets printed.
• Fit Height: If this is set, RightReports will adjust the size of the control to its contents when the report is printed, and the specified Height will be ignored.
• Transparent: Whether the control should be transparent.
• Background Color: The background color of the control. When editing this a color chooser pops up.
• Foreground Color: The foreground color of the control. Only really useful for boxes and lines. When editing this a color chooser pops up.
• Font Typeface: (String Controls Only) The font name for the string control. When editing this a font chooser pops up.
• Font Style: (String Controls Only) The font style for the string control. When editing this a font chooser pops up.
• Font Charset: (String Controls Only) The font name for the string control. When editing this a font chooser pops up.
• Font Size: (String Controls Only) The font size for the string control. When editing this a font chooser pops up.
• Font Color: (String Controls Only) The color for the string control. When editing this a font chooser pops up.
• Stretched: (Image Controls Only) Whether the image should be stretched.
• Centred: (Image Controls Only) Whether the image should be centred.
• Tile: (Image Controls Only) Whether the image should be tiled.
• File: (Image Controls Only) The file name for the image to display here. Note that the image file has to be in the application directory. For now.
• Line Width: (Line and Box Controls Only) The line width to use when drawing the line or box. In pixels.
• Picture: (String Controls Only) A picture to use for displaying the string.
• Justify: (String Controls Only) Choose whether you want the string to be left, right or center justified within in the control.
• Fit to Width: When the report is printed, this string field will be made long enough to ensure that all the text (after fields values, etc. have been evaluated) is printed.
• Fit to Height: Same as above, but for height.
• Text Box: This is mainly for use with data source fields that are very long. You will not see the difference on the editor, but when this field is printed on the report, it will be printed as a text box.
• RTF: In the case that Text Box above is on, this enables Rich Text Format. Again, you will not see the difference in the editor, only on the printed report. It is for use with dictionary file fields that have RTF enabled.

Blocks in a Report

A classical example of a Block in a report would be the following:

Suppose you had a secondary loop through Purchased Items for a report on Invoices. For each invoice, you want to print a header, the Purchased Items relating to that Invoice, and then the invoice footer. Naturally, if there are no Purchased Items relating to an Invoice, because they for example have been filtered out, you wouldn't want that entire invoice to print. To achieve this, you would make the invoice header the Block Start and Suppress it, and the invoice footer the Block End and Suppress that too. The actual band with the Purchased Item info on it, however, should be left alone.

The effect that this will have is the following: If there is at least one record in the secondary loop that does not get filtered out and its associating detail prints, all the details within the block will print. However, if there are no valid records and hence no details for Purchased Items print, none of the other details (i.e. the invoice header and footer) will print either.

In your Report Structure List, this scenario would look something like the following:

The stars represents bands with "Suppress if Block Empty" switched on, the closing angular bracket indicates a block start, and the opening angular bracket indicates a block end.

Functions and Variables in the Report

As was mentioned above in the section on the Property Editor, you can add variables to your report using the Global and Local tabs. Placing the name of this variable in angular brackets in a string on the report then causes the value of the variable to print out when the report is printed.

Note that there are three types of variables:

• User: When the report is printed, the user will be prompted on the PrintReport screen for the values of these variables before printing starts. The value for the prompt should be entered in the Else Value field in the list. You can specify the initial value for this variable in the Value field.
• Computed: These variables are computed either by Totalling (see Secondary Loops), Calculations, or they contain the values specified in the Value field in the list. The value in the Value field can be an expression, and can contain calls to functions available on the Functions Tab.
• Conditional: Here you can specify a Condition, Value and Else Value.

If you want functions to be available to the user at runtime, you need to take the following steps:

• Create the function in your application.
• Global Extension, and to the Custom Functions Tab.
• Add your procedure to this list.

There are already a number of built-in functions that ship with RightReports. Since they are already loaded they’re descriptions can be viewed as usual on the Functions Tab.

Tip: Say you have created your own clip function, called MyClip, and want this function to be called whenever the user calls “clip”. You will notice that Clip has already been bound by RightReports (to the usual Clarion Clip function). You need to make sure you unbind clip before binding it. So your code in the RightReportsBind embed point would be

UnBind(‘clip’)
Bind(‘clip’, MyClip)

Another Tip: Your custom function needs to take only string parameters, and it can only return strings, too. This is a limitation brought about by the Clarion Bind() procedure.

Printing Variable and Field Values

Putting angular brackets around a word indicates to the report printing engine that this is possibly a local or global variable (see the Property Editor), or a field in one of your report tables. When printing the report, RightReports will replace that part of the string with the current value of the variable, or with the value in the field of the current record in the table.

You can find all the local and global variables available to this report on the Local and Global tabs of the Property Editor. All the fields of the tables used in your report can be seen on the Fields Tab of the Property Editor. If your report is a Graphic report, you can drag and drop these fields onto any report band in the Graphic Band Editor above the field list.

Built-In Keywords

There are some built-in keywords such that if they are encountered in a string in angle brackets, RightReports will perform a certain action. The are essentially variables and are treated in exactly the same way. The following are examples:

• <formfeed>: When RightReports runs into this, it immediately starts a new page. For text reports it starts a new page immediately and prints the remainder of the band its on on the next page. For graphic reports, it finishes printing the current band before starting a new page.
• <page>: This will be replaced by the current page number.
• <linenumber>: Only for text reports. This will be replaced by the current line number on the page.

Renaming Table Fields

Suppose one of your table fields has a name that obscures its meaning, such as INV:rn, which stands for the invoice number. It is possible for users to see and use an alternative name in the report editor, which may, for example, be more descriptive and hence easier to work with, such as INV:InvoiceNumber. To do this, take the following steps:

• Go to the table field in your Dictionary
• Go to the User Options of that field
• Enter a new option called RRName and set it to whatever you would like the field to appear and be used as in the Graphic Report Editor

Excluding Tables and Fields from the Files List

There will quite possibly be some tables in your dictionary that you want to hide from the users on the Fields Tab. The way to do this is as follows:

• Go to the table in your dictionary
• Right-click and choose Properties
• Go to the Options Tab
• Insert a property called NoReports and set its value to 1
• Recompile your app

Once you have suppressed a table in your dictionary in this way, you can unsuppressed it by going to the Files Tab on the Global Extension. You will see that it is also possible to suppress files that have not been suppressed in the dictionary here.

In order to suppress specific fields of a given table in your dictionary, the process is the same as the above. You can just follow the five steps mentioned above to add the NoReports user option to the table field in your dictionary.

Preventing Users from Editing a Report

It is possible to prevent users from editing a report by setting the EditAccess property in the RRDefinition file to a value greater than 0. If this is the case for a report, the Update window will open in view-only mode.  The way the value of RRDFN:EditAccess is determined is left up to the programmer, and it is, for obvious reasons, not included in the Properties List for the report on the editor.

Preventing Access to Table Records

It is also possible to prevent a user from accessing certain records in the report tables when printing the report. In fact, it is possible to filter out any records of any table that the report loops through. To do this, you need to take the following steps:

• Go to the RightReportsPrint procedure
• Look for: ThisPrinter.CallNextRecord - Inside Loop
• Expand this tree and look for the file you want to filter
• Insert some filtering code. It may look something like this: if fil:fieldname < 0 then cycle.

The code you are embedding into looks like this:

 loop
   CallResult = self.NextRecord()
   !Embed code here to filter out records
   if CallResult
     ReturnValue = CallResult
     break
   end
   if 0
   elsif self.CurrentDataSource.Name = 'MyFile'
      !Your embed point is here
      if fil:FieldName < 0 then cycle.
   elsif self.CurrentDataSource.Name = 'MyFile2'
   end
   ReturnValue = 0
   break
 end

So basically this allows you to loop until you find an unfiltered record. You can even set the ReturnValue to a non-zero value to stop the processing of the current file completely.

The Report Previewer

As can be seen on the Global General Tab, it is possible to choose a previewer for your generated reports besides the default RightReports or ABC ones. The way to go about using such a 3rdparty previewer depends on the product, but the general idea is as follows:

• Add the Global Extension for the specific 3rdparty reporting tool who's previewer you want to use
• Select the desired previewing tool on the Global General Tab, under Previewer.
• There will possibly appear a new tab on the RightReports global extension, next to the General Tab - fill in the neccesary details here.

At the moment RightReports supports the IceTips, CPCS, RPM, ABC and RightReports-built-in report previewers. It is also possible to hand code your own call to a previewer, should you wish to choose that option. If you have any other previewers you would like to see included in our hard-coded list, please do not hesitate to contact us at support@capesoft.com.

The RightReportsPrint Procedure

RightReportsPrint is the procedure responsible for printing the report created by the report editor. At the moment, the RightReportsPrint procedure is imported as a source procedure and the code is hence available to you as a programmer. It is recommended that the majority of the code be left alone. There are, however, certain situations in which you may want to edit the code.

For example, you want to use your own Report Previewer. In this case, you could hand-code the call to the previewer yourself. Choose the Hand code option on the General Tab of the Global Extension, and follow the instructions laid out on the Hand coded Previewer tab that appears. Alternatively, you can do a search in the RightReportsPrint procedure for RightReportsPreview. You can replace this function call with your own.

Printing to a PDF File

As you saw on the RightReportsPrint Window, you can choose to output your report to a number of formats. One possibility is to output to PDF. To enable this, you need to take the following steps:

• Make sure you have abprpdf.inc and abprpdf.clw somewhere in your path. This class ships with Clarion 6 Enterprise Edition, but not with Professional edition.
• Go to the Global General Tab on the RightReports Global Extension, tick the Enable printing to PDF checkbox.

Printing to Word and Excel

As was mentioned before, it is possible to output to a number of different formats. Among these is the possibility to send the report output to a Microsoft Office Excel or Word file. Note that you need CapeSoft Office Inside version 2.63 or later. To enable this feature you need to take the following steps:

• Add the Office Inside Global Extension to your application.
• Note: If you are using Legacy, you need to enable the "Enable the use of ABC classes" checkbox on the Classes Tab of the Global Properties of your app.

If you would like the user to preview the output document automatically, then you need to add the HyperActive global extension template to your application as well.

Importing and Exporting a RightReports Report

It is possible for you to export a Report from RightReports into an XML format, and to import such a report again too. The idea here is to make reports portable. For example, this feature enables you to export a report, send the resulting XML file to a client, and he or she can then import the report into their system with minimal fuss. In addition, by exporting a report, you ensure that you have a saved copy in case you need to revert back to it for whatever reason. Re-importing an exported report also mimics the copy-paste action.

Note that this feature requires require XFiles 1.61 or later. To enable this feature, you need to take the following steps:

• Import the RRImportExportABC.txa (or ImportExportLegacy.txa) file into your application
• Add the global xFiles Extension to your application.
• The RightReportsImport and RightReportsExport procedures each has a RightReports Extension that generates the necessary code. They look something like this:

There is one option allowing to to control which reports may be imported into your program. If an exported report does not have this identifier, importing it will fail. The idea is that programs with different dictionaries will clearly not be able to support the same reports. Hence, using the dictionary name here seems like a good idea.

Importing Reports from a TXR File

RightReports can import reports that were created using Clarion's Report Writer with ease. To enable this feature, you need to take the following steps:

• The RightReportsImportTXR procedure is imported when you import the RightReportsFunctions.txa file.
• You just need to call this procedure from an applicable place in your application.

This procedure merely opens a window asking the user to specify the relevant TXR file before importing all the reports in that TXR into the RightReports report database. These reports then become available in the RightReportsBrowse, and can be edited and printed as usuall RightReports reports from this point on.

Embed Points for the Enthusiastic Coder

The RightReportsPrint class generates a number of procedures into the RightReportsPrint procedure where you can embed some of your own code.