A report typically presents most of its information in textual format. In fact, we can safely assume that all reports contain text. Even if a report consists primarily of charts or pictures, it still uses text to label charts, display titles, describe the charts or pictures, and so on.
Textual information can be
Static text, which is text that you type in the report. You use static text in a report title, column headings, or to write a summary about the report.
String, number, or date values that are derived from data set fields. The majority of information in a report typically comes from data set fields.
String, number, or date values that are derived from JavaScript expressions. Reports often contain information that is calculated, such as the report-generation date, or the number of records in a report table.
Textual information can be as short as a single word, or span multiple paragraphs, even pages. BIRT Report Designer handles all lengths of text elegantly. When you insert a textual element, you do not need to worry about specifying an element size that is large enough to display all the text. BIRT Report Designer automatically adjusts the size of elements to accommodate their contents.
To support the wide variety of text that a report can display, BIRT Report Designer provides a rich set of textual elements. Table 10-1 describes these elements, and Figure 10-1 shows a report that displays the different types of textual information.
Table 10-1. Descriptions of BIRT textual elements
Use to | |
|---|---|
Data | Display dynamic values that are derived from data set fields, computed fields, or JavaScript expressions. You can add literal, or static, text to the dynamic data. Doing so, however, changes the entire expression to a string, and, if the dynamic value is a number or a date, you can no longer format it as a number or a date. |
Dynamic text | Display memo or Character Large Object (CLOB) data from a data set field. This type of data typically consists of large amounts of text. |
Label | Display a small amount of static text, such as a report title or column heading. |
Text | Display the following types of user-specified text:
|
Figure 10-2 shows how the report in the previous illustration appears in the layout editor.
In many cases, you can use several textual elements to accomplish the same task. For example, you can use a label element, a text element, or a data element to display a static report title like the one in the following example:
Sales Report for Quarter One, 2005
When you start applying complex formats or combining static text with dynamic data, you need to use the appropriate textual element to achieve the best results. This section provides guidelines and examples for determining the best textual element to use for different purposes. When you understand the differences among the textual elements, read the rest of this chapter for details about using each element.
The previous example showed how you can use a label, text, or data element to display a static title. If, however, you want to format words in the title differently, as shown in the following example, you can accomplish this task only by using the text element. With the label and data elements, formats apply to the entire string.
Sales Report for Quarter One, 2005To display the following text, where Order Total: is static text, and the number is a dynamic, or calculated, value, you can use a text element or a data element:
Order Total: 74050
If, however, you want to format the dynamic value so that it appears as a currency value with comma separators and decimal places, as shown in the following example, use the text element. The text element enables you to format different parts of text differently.
Order Total: $74,050.00
Alternatively, you can use a label element and a data element to display the preceding text. Use the label element to display the static text portion, Order Total:, and the data element to display the dynamic portion, as shown in Figure 10-3. When the data element consists of just the number value, you can use the Format Number property to format the number.
Figure 10-4 shows the output of the preceding report design.
The difference between using the label and data elements and using the text element is how you control the space between the static text and the dynamic value. Using the text element, you can easily specify one character space between the two. If you use the label and data elements, the spacing is determined by various factors, such as text alignment and column widths. In the previous example, the label element and data element are both right-aligned.
Many data sources store large amounts of text that contain internal formatting, as shown in the following example. Data like this is typically stored in CLOB fields.
<html><b>Customer log 04/12/05 13:45:00</b><br>Customer called to enquire about order. He says order 2673-9890 was supposed to arrive on 04/10/05. Records show that the order is on backorder. Customer says he received no notification about the status of his order. He wants to cancel the order if it is not shipped by 04/15/05.<br><i>Action Items:</i><ul><li>Call distributor about delivery status. <li>Send email to customer about delivery status.</ul></html>
To display the text with the specified HTML formats, you can use the text element or the dynamic text element. If, however, you want to combine static text with dynamic text, use the text element. If you add static text to the dynamic text element, for example, “Customer Issue ” + row[“Issue”], the dynamic data appears in the report exactly as it appears in the field, including the HTML tags.
Figure 10-5 shows how the text element displays the static text, Customer Issue:, with the dynamic text. The text element converts the HTML tags to formatting and layout attributes. For example, text within the <b> and </b> tags appears in bold.
Figure 10-6 shows how the dynamic text element displays the text when you add static text to the dynamic text. The HTML tags appear because the content is converted to string type.
An expression is any valid combination of literals, variables, functions, or operators that evaluates to a single value. Both the text element and the data element can display the results of any valid JavaScript expression, including multiline expressions, such as the one in the following example:
if (row["creditScore"] > 700){
displayString = "Your loan application has been approved."
}
else{
displayString = "Your loan application has been denied."
}The main difference is that it is easier to edit JavaScript expressions in a data element. When you double-click a data element, its value expression appears in Expression Builder, which uses color for keywords and provides easy access to JavaScript functions and operators.
When you use a text element, its contents appear in the text editor. The first time that you specify a dynamic value in the text editor, Expression Builder appears to help you construct the expression. When the expression is inserted in the text editor, you cannot relaunch Expression Builder to edit the expression. You can edit the expression in the text editor, but the text editor does not provide color coding or access to JavaScript functions or operators.
You can place a dynamic text element directly on the page or in any of the container elements. Typically, you place it in a table or a list because the dynamic text element displays CLOB data from a data set field, and only the table and list elements iterate through the rows in a data set.
Unlike most data set fields, you do not simply drag a CLOB field from Data Explorer and drop it in the table or list. You can, but if the CLOB data is HTML text, the data element displays the contents of the field exactly as it appears, including the HTML tags. The dynamic text element, on the other hand, is designed to correctly display data that is stored as HTML.
As with any element that displays data set data, you must create a column binding that refers to the data set field. The column binding, in turn, needs access to the data set. If you insert the dynamic text element in a table or list that is already bound to a data set, the column binding has access to the data set. If the table or list is not bound with a data set, you must first bind the table or list with the data set.
How to use a dynamic text element
Make sure the table or list in which you want to insert a dynamic text element is bound to the data set that contains the CLOB data. To verify or create the data set binding:
Create a column binding that refers to the data set field that contains the CLOB data:
On the table’s Binding page, choose Add.
On Expression Builder, choose Available Data Sets, choose the data set, then double-click the CLOB field. Choose OK to save the expression. The new column binding appears in Data Binding with the column name highlighted.
Replace the name New Binding with a name of your choice, then choose OK.
Drag the dynamic text element from the palette, and drop it in the table or list.
On Expression Builder, choose Available Column Bindings, choose the table under Sub-Category, then double-click the column binding you created. Choose OK to save the expression.
In the layout editor, select the dynamic text element. Property Editor displays the properties of the dynamic text element.
Choose General properties, then choose one of the following values for Content type:
Auto
Choose this value if you do not know the format of the field contents. If the content contains HTML tags, BIRT Report Designer interprets it as HTML and displays the content correctly. If the content is plain text, BIRT Report Designer displays it correctly also.
HTML
Choose this value if you know that all the field contents are HTML.
Plain
Choose this value to display the field contents exactly as they appear in the data source. If the content contains HTML tags, BIRT Report Designer displays the HTML tags.
Preview the report to verify that the report displays the text from the specified data set field.
You can place a label directly on the page or in any of the container elements. When you insert a label, the layout editor displays an empty label with a cursor in it, as shown in Figure 10-7.
Start typing the text that you want to display, then press Enter when you finish.
Figure 10-8 shows the result.
You can edit the text in the label by double-clicking the label or by selecting the label and pressing F2, then typing the new text.
You can change the format of the text by selecting the label, then setting the desired style properties in the property editor. You can, for example, specify a different font, text alignment, size, or color. These properties apply to the entire text string. You cannot, for example, set one word to bold and another to italic. If variable formats are a requirement, use a text element instead.
You can place a text element directly on the page or in any of the container elements. When you insert a text element, the layout editor displays the text editor, as shown in Figure 10-9.
First, decide what type of text you want to create. You have two choices:
Plain text
HTML or dynamic text
HTML or dynamic text enables you to create highly formatted text using HTML tags or CSS properties. The text can contain placeholders for data set field values and expressions, which enable you to mix static text with dynamically generated values. Plain text, on the other hand, cannot contain internal formatting or dynamic values. A text element that is set to plain text functions like a label element.
After you select the text type, type the text that you want to display in the report. If you selected HTML/Dynamic text, you can use HTML tags or CSS properties in the text. You can type the tags manually, or you can insert the commonly used HTML tags that the text editor provides.
The following sections provide a few examples of text you can create using a text element of HTML/Dynamic type.
Using HTML, you can format individual words and lines in a text element. The following example shows two lines with different font sizes and styles.
Text that you supply:
<CENTER><B><span style="font-size: larger"> Shipped Orders Report </B></span><BR> <FONT size="small">For the month of March</FONT></CENTER>
Output:
BIRT Report Designer provides a useful tag, VALUE-OF, which you can use to insert a dynamic value in a text element. Using the VALUE-OF tag, you can insert any JavaScript expression.
The following example shows static text combined with a value that a JavaScript function returns.
Text that you supply:
Report generated on <VALUE-OF>new Date()</VALUE-OF>
Output:
Report generated on Jan 19, 2006 12:30 PM
The following example shows static text combined with a conditional expression and a field value expression.
Text that you supply:
Dear <VALUE-OF>row["Sex"] == "M" ? "Mr." : "Ms."</VALUE-OF>
<VALUE-OF>row["Name"]</VALUE-OF>,Output:
Dear Mr. Scott Johnson, Dear Ms. Ella Fitzgerald,
As the example shows, a conditional expression can have one of two values based on a condition. The syntax for this conditional expression is
condition ? value1 : value2
If the condition is true, the expression has the value of value1; otherwise, it has the value of value2.
Alternatively, you can use an if...else statement within the VALUE-OF tag. The following text displays the same results as the preceding conditional expression:
Dear <VALUE-OF>if(row["Sex"] == "M"){
Title = "Mr."
}
else{
Title = "Ms."
}</VALUE-OF>
<VALUE-OF>row["Name"]</VALUE-OF>,The following example shows how to use the VALUE-OF tag to insert dynamic values that data set fields return.
Text that you supply:
Dear <VALUE-OF>row["contact_firstname"]</VALUE-OF>,
<p>
Thank you for your recent order. Order <VALUE-OF>
row["orderID"]</VALUE-OF> will be shipped by <VALUE-OF>
row["shipByDate"]</VALUE-OF>.Output:
Dear Bob, Thank you for your recent order. Order 1115 will be shipped by Apr 17, 2005 12:00AM.
You can display field values in a text element only if the following two requirements are met:
The text element has access to the data set that contains the fields.
If you place the text element directly on the page, you must bind the text element to the data set that contains the field value. To do so, select the text element, choose the Binding tab in the property editor, then select the data set to which to bind. Placing the text element directly on the page, however, displays only one occurrence.
If you place the text element in the detail row of a table or a list to display all values of a data set field, bind the table or list to the data set.
A column binding is created for each data set field. The column binding refers to the data set field. The VALUE-OF tag, in turn, refers to the column binding.
The previous examples show how to use the VALUE-OF tag to insert dynamic values that a JavaScript function or a field returns. Sometimes the returned values are not in the format that you want. You can reformat the values using the format attribute, as shown in the following example.
Text that you supply:
<VALUE-OF format="MM-dd-yy">new Date()</VALUE-OF><br> <VALUE-OF format="$#,###.00">row["orderTotal"]</VALUE-OF><br> <VALUE-OF format="(@@@) @@@-@@@@">row["phone"]</VALUE-OF>
Output:
04-17-05 $321,000.00 (415) 123-5555
The format pattern must be enclosed in quotation marks. You can use any format pattern that the Format Number, Format DateTime, and Format String properties support. Information about these properties is in Chapter 11, “Formatting Report Content.”
Sometimes values in a data set field contain HTML text. If you insert such a field in a report, BIRT Report Designer displays the content of the field exactly as it appears in the data source, including the HTML tags.
To display the text with its intended formatting, use a text element or a dynamic text element instead of a data element. As described earlier in this chapter, the text element enables you to add static text to the dynamic text, whereas the dynamic text element displays all the HTML tags if you add static text.
To use the text element, select HTML/Dynamic text as the text type, then use the VALUE-OF tag to insert the value of the field, and set the format attribute to HTML, as shown in the following example.
Text that you supply:
Notes: <VALUE-OF format="html">row["CustomerNotes"]</VALUE-OF>