External types in a BIRT report-layout event handler

This topic reviews the EGL external types that you use when coding a report-layout event handler. For background information, see "EGL BIRT reports," "BIRT handler" and "BIRT report-layout event handlers."

CellInstance

A variable of type CellInstance references a cell in a report table or grid. One background detail is that the report designer or event handler can define a cell by combining columns, rows, or both columns and rows.

The variable makes the following fields available:
  • columnNumber is of type INT and contains the column number of the cell being created
  • columnSpan is of type INT and contains the number of table or grid columns occupied by the cell
  • rowSpan is of type INT and contains the number of table or grid rows occupied by the cell

The functions and fields described in the ReportElementInstance section are also available.

Here is an outline of an event handler used for an element of type CellInstance:
function myFunction( myCell CellInstance, myContext ReportContext ) 
   { eventType = onCreate, elementName = "myTable", rowNumber = 2 }
   if (myCell.columnNumber == 1)
      ;
   end
end

DataInstance

A variable of type DataInstance references a report-layout element that contains data, whether from a data source or a computation. The variable makes the following field available:
  • value is of type ANY and contains the value of the bound expression associated with the element

The fields and functions described in the ReportElementInstance and ReportItemInstance sections are also available.

Here is an outline of an event handler used for a element of type DataInstance:
function myFunction( myData DataInstance, myContext ReportContext ) 
   { eventType = onCreate, elementName = "DepartmentName"}
   if (myData.value == "Sales")
      ;
   end 
end

DynamicTextInstance

A variable of type DynamicTextInstance references field that contains character large object (CLOB) data; for example, a memo. The variable makes the following field available:
  • text is of type STRING and contains the report text

The fields and functions described in the ReportElementInstance and ReportItemInstance sections are also available.

Here is an outline of an event handler used for a element of type DynamicTextInstance:
function myFunction( myText DynamicTextInstance, myContext ReportContext ) 
   { eventType = onCreate, elementName = "resultOfEvaluation" }
   if (myText.text == "<b>Promote!</b>";
      ;
   end
end

GridInstance

A variable of type GridInstance references a grid, which is a simple, table-like structure. The only functions available are those described in the ReportElementInstance and ReportItemInstance sections.

Here is an outline of an event handler used for a element of type GridInstance:
function myFunction( myGridInstance GridInstance, myContext ReportContext ) 
   { eventType = onCreate, elementName = "myGrid" }
   ;
end

ImageInstance

A variable of type ImageInstance references an image, which is accessed by a reference to one of the following locations:
  • A web or file address in the form of a Uniform Resource Identifier (URI) such as http://www.example.com/myImage.gif or file:///c:/myImage.gif. In this case, the BIRT designer considers the image to be of type URI.
  • A file name, in which case the file is assumed to be in the BIRT resource folder. (You establish a reference to that folder by clicking Windows -> Preferences ->Report Design -> Resource and then specifying the folder.) In this case, the BIRT designer considers the image to be of type File.
  • The design file itself. In this case, the BIRT designer considers the image to be of type Embedded.
  • A column of type BLOB (binary large object) in a data set, in which case the BIRT designer considers the image is to be of type Dynamic.

When you work in the BIRT designer, you specify the type of image at the Edit Image Item screen. BIRT documentation refers to images of type URI and File as linked images.

The variable makes the following fields available:

  • altText is of type STRING and contains the alternate text, which is the text to display if the output is in HTML and a particular web browser cannot display the image.
  • dynamicImageData is of type BLOB and contains the content of an image of type Dynamic.

    The Java-code getter and setter methods are getData and setData.

  • embeddedImageName is of type STRING and contains the name of an image of type Embedded. That name is specified in the report design file and is distinct from the element name for the image.

    The Java-code getter and setter methods are getImageName and setImageName.

  • imageURI is of type STRING and contains the web or file address that refers to an image of type URI.

    The Java-code getter and setter methods are getURL and setURL.

  • linkedImageURI is of type STRING and contains the web or file address that refers to a linked image (that is, to an image of type URI or File). You cannot assign a value to this variable.

    The Java-code getter method is getURI.

  • mimeType is of type STRING and contains the media type such as "image/gif", "image/jpeg", "image/png", and "image/tiff".

    The Java-code getter and setter methods are getMimeType and setMimeType.

  • resourceFolderImageFile is of type STRING and contains the name of an image of type File.

    The Java-code getter and setter methods are getFile and setFile.

You can use the event handler to change the reference to an image, even if the type of image specified in the event handler is different from the type of image specified in the report design. The following event handler references an image of type URI and is valid even if the design indicates that the image is of type Embedded:
function changeImage( theImage ImageInstance, myContext ReportContext )  
   { eventType = onCreate, elementName = "salesGraphic" }
   theImage.imageURI == "file:///c:/images/myGraphic01.bmp";
end
Similarly, the following event handler references an image of type Embedded and is valid even if the design indicates that the mage of type URI:
function changeImage( theImage ImageInstance, myContext ReportContext )
   { eventType = onCreate, elementName = "salesGraphic02" }
   theImage.embeddedImageName = "myGraphic02.bmp";
end

LabelInstance

A variable of type LabelInstance references a label, which is text that lacks HTML formatting and does not reflect a computed value. The variable makes the following field available:
  • text is of type STRING and contains the label text

The fields and functions described in the ReportElementInstance and ReportItemInstance sections are also available.

Here is an example of an event handler used for a element of type LabelInstance:
function myLabelFunction( theLabel LabelInstance, myContext ReportContext )  
   { eventType = onCreate, elementName = "remark_label" }
   balance float = theLabel.getRowData().getColumnValue("account_balance");
   if( balance > 0 )
      theLabel.text = "Balance Due";
      theLabel.getStyle().color = "red";
   end
end

ListInstance

A variable of type ListInstance references a list. The only functions available are those described in the ReportElementInstance and ReportItemInstance sections.

Here is an outline of an event handler used for a element of type ListInstance:
function myFunction( myList ListInstance, myContext ReportContext )
    { eventType = onCreate, elementName = "employeeList" }
    ;
end

ReportContext

An event-handler parameter of type ReportContext provides access to the report parameters. Two functions are available:
  • setParameterValue sets the value of a report parameter, which is identified by name:
     reportContext.setParameterValue
     ( parameterName STRING in, parameterValue ANY in ) 
  • Similarly, getParameterValue gets the value of a report parameter:
     reportContext.getParameterValue
     ( parameterName STRING in) returns (ANY)  

ReportContext is not a report-layout element type and is not relevant to our sections on ReportElementInstance and ReportItemInstance.

ReportElementInstance

The type ReportElementInstance corresponds to a Java™ superclass and is superior to all other report-layout element types, including CellInstance, RowInstance, and the Java superclass ReportItemInstance. The field and functions described in this section are available for a variable of any of those types.

Some fields and functions access the following Cascading Style Sheets (CSS) units of measurement: cm (for centimeter), em (for the height required for a specific font), ex (for the font-specific height of the letter 'x'), in (for inch), mm (for millimeter), pc (for pica), % (for percentage of the height of the enclosing element), pt (for point), and px (for pixel). For background detail, see http://www.w3.org/TR/CSS21/syndata.html.

The ReportElementInstance fields are as follows:
  • height is of type STRING, contains the height of the element being created, and includes a unit of measurement, as mentioned earlier. The string has no spaces; for example, "12pc".
  • width ;is of type STRING, contains the width of the element being created, and includes a unit of measurement, as mentioned earlier. The string has no spaces; for example, "12pc".
The ReportElementInstance functions are as follows:
  • getParent returns the parent element. This function returns a cell element, for example, if the qualifier used in the invocation refers to a label element within the cell.
    element.getParent()returns (ReportElementInstance)
    As shown, the function returns an element of type ReportElementInstance. If the function returns an element of type CellInstance and you wish to access the field columnNumber in that element, you must cast the returned value. Here is an example:
    function myLabelFunction( theLabel LabelInstance, myContext ReportContext  ) 
       { eventType = onCreate, elementName = "remark_label" }
       myReportInstance ReportElementInstance = theLabel.getParent();
       if (myReportInstance isa CellInstance )
          myCellInstance CellInstance = 
             myReportElementInstance as CellInstance;
          if (myCellInstance.columnNumber == 1)
             ;
          end
      end
    end
  • getRowData returns an object of type RowData. The returned object contains a set of column bindings as listed in the BIRT Report Designer, in the Property Editor view for the report. (The bindings are listed in the Bindings tab of that view). You use the object to invoke the function getColumnValue, which retrieves the value of a given column binding. For details on that function, see the section on RowData.
    element.getRowData() returns (RowData)
  • getStyle returns an object of type Style, which contains the values that reflect the CSS style in use. For details on accessing those values, see the section on Style.
    element.getStyle() returns (Style)
  • getNamedExpressionValue returns the value of the specified named expression. The named expressions are listed in the BIRT Report Designer, in the Property Editor view for the report.
    element.getNamedExpressionValue 
         (expressionName STRING in) returns (ANY)
    You can use this function to access JavaScript expressions defined in the report design. For example, for a label named total, you can define an expression named BalanceTotal as Total.sum(row["account_balance"]); and in the onCreate event, you can set the label text as follows:
    function onTotalLabel( l LabelInstance, c ReportContext )
       { eventType = onCreate, elementName = "total" }
       l.text = "Total balance = " + l.getNamedExpressionValue("BalanceTotal");
    end

ReportItemInstance

The type ReportItemInstance corresponds to a Java superclass and is subordinate to ReportElementInstance. The following field is available from a variable of any of the report-layout element types other than CellInstance, RowInstance, or ReportElementInstance:
  • helpText is of type STRING and contains the help text associated with the element

RowData

RowData is not a report-layout element type like LabelInstance, and no event handler uses a parameter of type RowData. Instead, an object of type RowData is returned when you invoke element.getRowData(), which is described in the ReportElementInstance section.

The RowData functions are as follows:
  • getColumnCount returns the number of column bindings:
      element.getRowData().getColumnCount() returns (INT)
  • getColumnName returns the name of a column binding, which is identified by an index number:
      element.getRowData().getColumnName( columnNumber INT in )returns (STRING)

    The first column is number 1, not 0.

  • One form of getColumnValue returns the value of a column binding, which is identified by name:
      element.getRowData().getColumnValue( columnName STRING in )returns (ANY)
  • A second form of getColumnValue returns the value of a column binding, which is identified by an index number:
      element.getRowData().getColumnValue( columnNumber INT in ) returns (ANY)

    The first column is number 1, not 0.

RowInstance

A variable of type RowInstance references a row in a report table. The only functions available are those described in the ReportElementInstance section.

Here is an outline of an event handler used for an element of type RowInstance:
function myFunction( myRow RowInstance, myContext ReportContext ) 
   { eventType = onCreate, elementName = "myTable", rowType = detail, rowNumber = 2 }
   ;
end

Style

Style is not a report-layout element type like LabelInstance, and no event handler uses a parameter of type Style. Instead, an object of type Style is returned when you invoke element.getStyle(), which is described in the ReportElementInstance section.

After you receive the object, you can access one or the other Style value by referencing a Java field name. In each case, the field is of type STRING. For example, you can set the background color for the element myElement as follows:
   myElement.getStyle().backgroundColor = "red";
Similarly, you can retrieve the background color into a variable of type STRING:
   myColor STRING;
   myColor = myElement.getStyle().backgroundColor;

As shown in the next table, many Java fields can be accessed in this way.

Field name Meaning
backgroundAttachment Specifies whether a background image scrolls with the rest of the page or is fixed in place. The value is "scroll" (the default) or "fixed".
backgroundColor The background color of the element.
backgroundImage The web or file address of the background image.
backgroundPositionX The horizontal position of the background image: "center", "left", "right", or a string that has a number and a unit of measurement; for example, "12pc". The string has no spaces. For more details on units of measurement, see the section on ReportElementInstance.
backgroundPositionY The vertical position of the background image: "center", "top", "bottom", or a string that has a number and a unit of measurement; for example, "12pc". The string has no spaces. For more details on units of measurement, see the section on ReportElementInstance.
backgroundRepeat Specifies whether a background image repeats: "repeat" (the default: repeat horizontally and vertically across the page), "no-repeat", "repeat-x" (repeat horizontally across the page), or "repeat-y" (repeat vertically across the page).
borderBottomColor The color of the bottommost border line. A color is available only if borderBottomStyle is set.
borderBottomStyle A value (if any) to describe the bottommost border line: "solid", "dotted", "dashed", "double".
borderBottomWidth The width of the bottommost border line: "thin", "medium", "thick". A width is available only if borderBottomStyle is set.
borderLeftColor The color of the leftmost border line. A color is available only if borderLeftStyle is set.
borderLeftStyle A value (if any) to describe the leftmost border line: "solid", "dotted", "dashed", "double".
borderLeftWidth The width of the leftmost border line: "thin", "medium", "thick". A width is available only if borderLeftStyle is set.
borderRightColor The color of the rightmost border line. A color is available only if borderRightStyle is set.
borderRightStyle A value (if any) to describe the rightmost border line: "solid", "dotted", "dashed", "double".
borderRightWidth The width of the rightmost border line: "thin", "medium", "thick". A width is available only if borderRightStyle is set.
borderTopColor The color of the topmost border line. A color is available only if borderTopStyle is set.
borderTopStyle A value (if any) to describe the topmost border line: "solid", "dotted", "dashed", "double".
borderTopWidth The width of the topmost border line: "thin", "medium", "thick". A width is available only if borderTopStyle is set.
canShrink Specifies whether to shrink the text area in HTML output if the content does not use the whole space: "false" (the default) or "true".
color The foreground color of the element.
dateFormat One of the standard date formats defined by BIRT:
  • "General Date", which describes (for example) "October 20, 1998 12:00:00 AM CDT"
  • "Long Date", which describes "October 20, 1998"
  • "Medium Date"; "Oct 20, 1998
  • "Short Date"; "10/7/98"
  • "Long Time"; "12:00:00 AM CDT"
  • "Medium Time"; "12:00:00 AM"
  • "Short Time"; "24:00"

BIRT also allows the report designer to define a custom format based on a pattern supported by the Java SimpleDateFormat class. The format "M/d/yyyy, E" might be used, causing the date in the current example to be displayed as "10/20/1998 Tues".

displayType Specifies whether the element is displayed in a separate block of text, on the current line within the current block of text, or not at all. The values are "block" (the default), "inline", and "none". The EGL displayType property is equivalent to the underlying, Java-specific display property.
fontFamily The font family: "serif" (the default), "sans-serif", "cursive", "fantasy", "monospace", and so on.
fontSize The font size of the text. One of the standard sizes defined by BIRT: "medium" (the default), "large", "larger", "small", "smaller", "x-large", "x-small", "xx-large", or "xx-small". Alternatively, the value is a string that has a number and a unit of measurement; for example, "12pc". The string has no spaces. For more details on units of measurement, see the section on ReportElementInstance.
fontStyle The font style of the text: "normal" (the default), "italic", or "oblique".
fontVariant The font variant: "normal" (the default), "small-caps".
fontWeight The font weight of the text: "normal", "bold", "bolder", "lighter", or a hundreds value from 100 through 900.
letterSpacing The space between letters. The default value is "normal" (a font-specific value). Alternatively, the value is a string that has a number and a unit of measurement; for example, "12pc". The string has no spaces. For more details on units of measurement, see the section on ReportElementInstance.
lineHeight The line height: The default value is "normal" (a font-specific value). Alternatively, the value is a string that has a number and a unit of measurement; for example, "12pc". The string has no spaces. For more details on units of measurement, see the section on ReportElementInstance.
marginBottom Space between the bottommost line in the border and the horizontally next element. The string has no blanks and includes a unit of measurement; for example, "12pc". For more details on units of measurement, see the section on ReportElementInstance.
marginLeft Space between the leftmost line in the border and the vertically previous element. The string has no blanks and includes a unit of measurement; for example, "12pc". For more details on units of measurement, see the section on ReportElementInstance.
marginRight Space between the rightmost line in the border and vertically next element. The string has no blanks and includes a unit of measurement; for example, "12pc". For more details on units of measurement, see the section on ReportElementInstance.
marginTop Space between the topmost line in the border and the horizontally previous element. The string has no blanks and includes a unit of measurement; for example, "12pc". For more details on units of measurement, the section on ReportElementInstance.
masterPage A string that identifies the master page.
numberFormat One of the standard number formats defined by BIRT. Examples include "General Number", "Fixed", "Percent", and "Scientific". BIRT also allows the report designer to define a custom format based on a pattern supported by the Java DecimalFormat class. The number format "$#,##0.00" might be used, causing 123456 to be displayed as $1,234.56.
paddingBottom Space between the content of an element and the bottommost line in the element's border. The string has no blanks and includes a unit of measurement; for example, "12pc". For more details on units of measurement, see the section on ReportElementInstance.
paddingLeft Space between the content of an element and the leftmost line in the element's border. The string has no blanks and includes a unit of measurement; for example, "12pc". For more details on units of measurement, see the section on ReportElementInstance.
paddingRight Space between the content of an element and the rightmost line in the element's border. The string has no blanks and includes a unit of measurement; for example, "12pc". For more details on units of measurement, see the section on ReportElementInstance.
paddingTop Space between the content of an element and the topmost line in the element's border. The string has no blanks and includes a unit of measurement; for example, "12pc". For more details on units of measurement, see the section on ReportElementInstance.
pageBreakAfter Specifies the circumstance in which a subsequent page break occurs: "auto" (the default, which indicates that the page break occurs automatically to fulfill other space requirements), "always", "avoid", "always-excluding-first", "always-excluding-last".
pageBreakBefore Specifies the circumstance in which the element follows a page break: "auto" (the default, which indicates that the page break occurs automatically to fulfill other space requirements), "always", "avoid", "always-excluding-first", "always-excluding-last".
pageBreakInside Specifies the circumstance in which a page break occurs within the element: "auto" (the default, which indicates that the page break occurs automatically to fulfill other space requirements), "avoid".
showIfBlank Specifies whether to show an element even if it is empty or if all its subordinate elements are empty: "false" (the default), "true".
stringFormat A format string based on a BIRT-defined system of symbols such as @ & | > <.
textAlign One of the values that reflects horizontal alignment: "left", "right", "center", "justify".
textIndent The indentation of text within the element. The string has no blanks and includes a unit of measurement; for example, "12pc". For more details on units of measurement, see the section on ReportElementInstance.
textTransform Specifies how to change the text placed in the element: "none" (the default: make no change); "capitalize" (capitalize the first letter in each word), "uppercase" (set all letters to uppercase), "lowercase (set all letters to lowercase).
verticalAlign One of the values that reflects vertical alignment: "top", "middle", "bottom".
visibleFormat Specifies whether the element is hidden when the report is output in a particular format: "all", "pdf", "html".
whiteSpace Specifies, for HTML output, how to handle the whitespace in the element text: "normal" (the default: remove extra white space and insert line breaks as necessary to keep the text within the element width); "pre" (retain white space in the element text, including line breaks); "nowrap" (remove extra white space without inserting line breaks). The specific behavior may vary by browser type and version.
wordSpacing The space between words. The default value is "normal" (a font-specific value). Alternatively, the value is a string that has a number and a unit of measurement; for example, "12pc". The string has no spaces. For more details on units of measurement, see the section on ReportElementInstance.

TableInstance

A variable of type TableInstance references a report table. The only functions available are those described in the ReportElementInstance and ReportItemInstance sections. The variable makes the following fields available:
  • caption is of type STRING and contains the table caption.
  • repeatHeader is of type BOOLEAN and indicates whether to repeat the table headers on pages after the first page. Valid values are true (the default) and false.
Here is an outline of an event handler used for a element of type TableInstance:
function myFunction( myTable TableInstance, myContext ReportContext ) 
   { eventType = onCreate, elementName = "myTable" }
   ;
end

TextInstance

A variable of type TextInstance references report text, which may have HTML formatting or reflect a computed value. The variable makes the following field available:
  • text is of type STRING and contains the report text

The fields and functions described in the ReportElementInstance and ReportItemInstance sections are also available.

Here is an outline of an event handler used for a element of type TextInstance:
function myFunction( myText TextInstance, myContext ReportContext ) 
   { eventType = onCreate, elementName = "conclusion" }
   if (myText.text == "<b>Promote!</b>";
      ;
   end
end

Feedback