Text components are similar to Label components. They provide much more flexibility than Labels, in that they allow HTML formatting inside of the definition for the text. They also allow for some special tags that will display data from a JavaScript environment. This becomes important if we want to add AJAX or dynamic DOM manipulation to our report. It is even possible to put in images without using the BIRT Image component and anchor tags.
For the following example we will build on to our Hello World report by adding in a list that will be formatted with HTML. The items will be Item 1, Item 2, and Item 3 respectively. Item 1 will be set to bold using HTML, whereas Item 2 and Item 3 will be left alone. For the purpose of this example, you do not need to be familiar with HTML as I will walk you through the steps. A detailed tutorial on HTML is beyond of the scope of this book.
- Open
HelloWorld.rptdesignfrom theClassic_Cars_BIRT_Reportsproject. - From the Palette, drag a
Textobject over to the Report Design pane, just below the Hello World label. TheTextelement icon is illustrated at the beginning of this section.
- The Edit Text Item dialog box will pop up. Here we can edit the type of text we want to appear, control the HTML formatting of the text, and get access to quick menus that will allow us to see a small sample of HTML code we can embed in a text object. At the very top of the dialog box, change the type of text from Auto to HTML.
- Go ahead and play around with the different types of formatting menus here; a drop-down menu with the name Formatting appears. Change the option from Formatting to Lists. Press the<DL> button that appears to the right of the drop-down list. We can see the editor will automatically create both the opening and closing tags for the list.
- Now click on the <LI> button. Do this three times. In between the
<LI>and</LI>tags, put the following labels in order:- Item 1
- Item 2
- Item 3
- Now, using mouse, highlight the Item 1 text between the first
<LI>and</LI>tags. With Item 1 highlighted, click on the<B> button at the top of the Edit Text Item dialog. This will automatically surround the Item 1 text with the tags<B>and</B>.
- Move the cursor below the
</DL>tag. Select the Dynamic Text tag from the drop-down list. Click on the<VALUE-OF> button, which will insert a<VALUE-OF>and</VALUE-OF>tag where the cursor is. TheVALUE-OFtag is a special BIRT tag that will insert dynamic text based on any number of values such as JavaScript results or data values at the time of the report generation.
- In between the
<VALUE-OF>and</VALUE-OF>tags, type innew Date();. This is a small piece of JavaScript code that will retrieve the current date. - We will also want to format this date. Move the mouse cursor to inside of the first
<VALUE-OF>tag, just to the right ofVALUE-OF. - Now under the
<VALUE-OF>tag on the top, with the drop-down box next to it, open the drop-down box and select Format DateTime.
- Select the date format that reads "MMM DD, YYYY".
- Click OK.
- We will see that a format was inserted next to the
VALUE-OFtag. Go ahead and click OK.
- Now click Preview. We can see that the Item 1 text is now in bold, and the place where the
VALUE-OFtag was located now contains the current date and time.
We can go back and change the formatting to use any standard Java formatting expression. In the example, instead of using the format dialog, we can change it using the format="YYYY-MM-DD", VALUE-OF tag attribute in the Edit dialog, and the date will be displayed as shown in the following screenshot:
We will notice two different date formats. One is from our VALUE-OF expression. The other is located in an area called the Master Page, which we will discuss later.
Of course, with some understanding of HTML there is a lot more we can do with this. The VALUE-OF tag also gives us a lot of flexibility once data becomes part of the picture, which we will see later on. With a little understanding of JavaScript, we can make some really dynamic things happen. With the combination of HTML and JavaScript, we can add some report interactivity.
The Dynamic Text component is very similar to the Text component using the VALUE-OF tag, except that it uses JavaScript, BIRT report objects, and CLOBS to display its text. For the time being, we needn't go into much detail about this as it will be covered in depth in the Practical Example building reports for Bugzilla chapter. For now we will go through a simple exercise to demonstrate how the Dynamic Text component can be used with JavaScript. In the following exercise, we will take a simple phrase and, using the JavaScript function to convert to upper case, we will display the text in all caps. A discussion on JavaScript and JavaScript programming is outside the scope of this book. For this exercise, one needn't know JavaScript; one just needs to understand that we are taking a string and converting it to uppercase.
- Open the
HelloWorld.rptdesignfrom theClassic_Cars_ BIRT_Reportsproject. - From the Palette, drag a
Dynamic Textobject to the Report Design pane, just below the Hello World label or the Text object from the previous exercise.
- The Expression Builder will pop up.
- We will notice this looks different than the Edit Text Item dialog from the previous exercise. The Expression Builder is a dialog that will be used a lot in BIRT. It is used to edit small, short JavaScript expressions that will usually return a single value. When we cover scripting in more depth, we will discuss the differences between the Expression Editor and the Script Editor Pane used in the Report Designer. Type in the following text, including the quotes: "Good-Bye World".
- At the bottom of the Expression Editor, we will notice three different list boxes. These are used as a quick reference for JavaScript objects and methods that can be used in an expression. Put a period at the end of the "Good-Bye World" text. Then, under the Category list box at the bottom of the Expression Editor, choose Native JavaScript Functions.
- A whole list of items will appear under the Sub-Category listbox. These are types of objects and methods we can work with. As "Good-Bye World" is a text string, select the String item.
- Now we have a list of methods we can use with the string "Good-Bye World". Make sure the cursor is after the period that was added after the "Good-Bye World" text. In the third list box, find and double-click on the
toUpperCase() : Stringitem. When we do that, we will notice that the method will get added to the place where the cursor is located.
- Click OK.
- Preview the report.
In the finished report, the string "Good-Bye World" now reads GOOD-BYE WORLD. This is a useful component when one needs to perform operations on data values, perform calculations, and do a few other things that would require dynamic, calculation-driven text. There are properties of components that can do similar things such as Maps and Highlights that can perform dynamic text substitutions, enumerate data values, and change formatting of text based on certain conditions. We will discuss these elements in depth later in the book.