Xbasic

A5_xb_runReport Function

Syntax

c output = A5_xb_runReport(p inputProps)

Arguments

inputPropsPointer

Defines the Report to run and various properties of the Report. This object can have the following properties:

inputProps.reportNameCharacter

The fully qualified report, label or letter name. For example:

Example

inputProps.reportName = "[email protected]"
inputProps.initialViewCharacter

Can either be 'HTML' or 'PDF'. Specify if you want to see a PDF or HTML view of the report. HTML is recommended as it is substantially faster. If the user wants a PDF version of the report, they can click the 'PDF' button on the report toolbar.

inputProps.filterCharacter

Report filter. In the case of a report based on .dbf tables, filter can use Xbasic functions. The .filter can use arguments. For example:

Example

country = :whatcountry

In the case of a report based on SQL data, it is recommended that you use the .sqlFilter property rather than the .filter property. If you do specify a .filter property for a SQL report, Alpha Anywhere will try to convert the .filter to a SQL filter. If the filter cannot be converted, the filter will be applied to the data after it has been loaded into a temporary .dbf table from the SQL database.

inputProps.orderCharacter

Order for the report.

In the case of a report based on SQL data, it is recommended that you use the .sqlOrder property rather than the .order property.

inputProps.sqlFilterCharacter

WHERE clause for a report based on SQL data. The sqlFilter can use arguments. For example:

Example

country = :whatcountry

It is recommended that you use arguments in the filter rather than literal values. The argument values can be passed in in the .arguments property. (See below)

inputProps.sqlOrderCharacter

Order clause for a report based on SQL data.

inputProps.argumentsCharacter

Argument values must be supplied if the report filter uses arguments.

A CR-LF delimited string indicating each argument, its type and value. For example:

Example

inputProps.arguments = <<%str%
arg1|c|John
arg2|n|23
arg3|d|12/18/1952
%str%
inputProps.componentAliasCharacter

Alias of the component. Only needed if the report initial view is HTML.

inputProps.reportDivCharacter

The name of the DIV where the report will be shown.

inputProps.widthCharacter

Width of the report

inputProps.heightCharacter

Height of the report

inputProps.styleNameCharacter

Only needed for HTML reports. Specify the style name (e.g. iOs, etc) for the style of the HTML controls in the HTML Report Viewer.

inputProps.pdfOptionsPointer

(Optional). In the case where the initial view is PDF, a crlf delimited list of PDF options. See Report.SaveAs for available PDF options.

inputProps.buttonsPointer

(Applies only when initialView is HTML)

By default, all of the buttons on the HTML Report View toolbar are turned on. These buttons are: Export as PDF, Export as Excel, Export as Word, Export as Text and Print HTML. You can optionally control whether a button is shown and you can control properties of each button (such as text, icon, style and bubble help).

The following properties are available to control the HTML Report View toolbar:

inputProps.buttons.pdfLogical

Set to .t. or .f. to control whether or not the PDF button appears on the Toolbar. If omitted, the default is .t.

inputProps.buttons.excelLogical

Set to .t. or .f. to control whether or not the Excel button appears on the Toolbar. If omitted, the default is .t.

inputProps.buttons.wordLogical

Set to .t. or .f. to control whether or not the Word button appears on the Toolbar. If omitted, the default is .t.

inputProps.buttons.textLogical

Set to .t. or .f. to control whether or not the Text button appears on the Toolbar. If omitted, the default is .t.

inputProps.buttons.printHTMLLogical

Set to .t. or .f. to control whether or not the Print HTML button appears on the Toolbar. If omitted, the default is .t.

inputProps.buttons.<buttonType>.textCharacter

<buttonType> must be: pdfButton, excelButton, wordButton, textButton, or printHTMLButton, depending on what type of button you are configuring. Allows you to specify the text label for the button. For example:

Example

inputProps.buttons.pdfButton.text = "PDF"
inputProps.buttons.<buttonType>.buttonTypeCharacter

Allows you to specify the button style. Options are: Text only, Image only, Text followed by Image, Image followed by text, Image above text, Text above image.

inputProps.buttons.<buttonType>.imageNameCharacter

Allows you to specify the image for the button (if the image is configured to show an image). If using a built in image, use this syntax:

Example

inputProps.buttons.pdfButton.imageName = "images/$$application.adobe.pdf.png.a5image"
inputProps.buttons.<buttonType>.bubbleHelpCharacter

Allows you to specify the bubble help for the button.

Description

Generates the HTML and Javascript to display a report.

Discussion

Action Javascript is typically used to generate reports in an application. If you want to dynamically choose the report to create, however, you must use another method to generate the report. The a5_xb_runReport() function can be used in an Ajax callback to dynamically run a report at run-time. When the report is finished running, the response is sent back to the client to display the report.

Example 

In this example, we show how you can create a UX component that allows a user to select a report and then click a button to print the report.

Assume that the UX component has the following controls:

  • A Dropdown called 'WhatReport' in which the user can select the report to print.

  • A control in which the user can enter the name of a state if the selected report is 'Customers'

  • A control in which the user can enter an invoice number if the selected report is 'Invoices'.

  • A button to print the selected report, filtered on the data in the appropriate control (state name or invoice number).

  • A static text control with this in it (this is where the report will be rendered):

    <div id="rep1"></div>

In this example, the button will make an Ajax callback to a function (called say 'printReportXB'). Here is how the printReportXB function would be defined.

function printReportXB as c (e as p)
    delete p

    'the p object we are going to define now is passed into
    'a5_xb_runReport() to define the report we want to print
    dim p as p
    dim report as c

    'the name of the report that the user selected is in the
    'e.datasubmitted.whatreport variable
    report = e.datasubmitted.whatreport

    'convert the short report name to a fully qualified report name
    if report = "customer" then
        p.reportName = "[email protected]"
        p.SQLFilter = "State = :whatstate "

        'set the value of the arguments property to define any arguments used
        ' in the filter
        p.arguments = "whatState|c|" + e.datasubmitted.stateName
    else
        p.reportName = "[email protected]"
        p.sqlfilter = "invoice = :whatInvoice"

        'set the value of the arguments property to define any arguments used
        ' in the filter
        p.arguments = "whatInvoice|n|" + e.datasubmitted.invoiceNumber
    end if

    'set the initial report view to HTML. Can also set to PDF
    p.initialView = "html"


    'since we are using HTML reporting we specify the alias of the host component
    p.componentAlias = e.tmpl.alias

    'the id of the div where the report will be shown
    p.reportdiv = "rep1"

    'the size of the report
    p.width = "12in"
    p.height = "4in"

    'the style to use for the HTML Report Viewer. We want the style to match the
    'style of the host component, so we pass in the style name used by the UX component
    p.styleName = e.tmpl.style_name

    'Turn off the 'Export to Text' button on the Report Toolbar
    P.buttons.text = .f.

    'Set the bubble help for the 'Print HTML' button to some text that uses
    'language tags
    P.buttons.printHTMLButton.bubbleHelp = "<a5:r>Print</a5:r>"

    dim js as c
    'Passing in tmpl and rtc is optional. however, if you don't then language tags
    'in the buttons will not be evaluated.
    'In this case, we used a language tag in the bubble help for one of the buttons
    js = a5_xb_runReport(p, e.tmpl, e.rtc)

    printReportXB = js

end function

This example demonstrates running a Project report. To run a Workspace report, the syntax for the fully qualified report name is <report name>@<workspace name>.alb. EG, [email protected].

Workspace reports are only recommended for use in Desktop applications. Use Project reports in a Web or Mobile Alpha Anywhere application.

Specifying PDF Options 

The PDF options parameters are defined as a CR-LF delimited list. A complete list of PDF options are listed in the Report.SaveAs article. The example below demonstrates how this is done:

dim pdfOptions as C
pdfOptions =<<%str%
DIM Concatenate as L
DIM HasWatermark as L = .T.
DIM MultilingualSupport as L = .T.
DIM EmbedFonts as L
DIM LinearizeForWeb as L
DIM Colors2GrayScale as L
DIM ConvertHyperlinks as L
DIM WatermarkType as C = "Text"
DIM WatermarkText as C = "D R A F T"
DIM WatermarkFontName as C = "Times New Roman"
DIM WatermarkFontSize as N = 172
DIM WatermarkRotation as N = 450
DIM WatermarkColorHex as C = "E8FED2"
DIM WatermarkHorizPos as N = 120
DIM WatermarkVertPos as N = -120
DIM WatermarkOnTop as L
DIM WatermarkPDF as C
DIM Encrypt as L
DIM OwnerPassword as C
DIM UserPassword as C
DIM CanPrint as L = .T.
DIM CanModifyDocument as L = .T.
DIM CanCopy as L = .T.
DIM CanAddNotes as L = .T.
DIM Use128BitKey as L = .T.
DIM JpegQuality as C = "Low"
%str%

You can also specify PDF options globally for the Alpha Anywhere project in the Web Project Properties. See PDF Printing Options for more information.

Additional Resources 

To learn more, watch the video below:

This video demonstrates running Workspace reports. In web or mobile applications, Project reports are used instead of Workspace reports.