Identification and Source Sections

Figure 3-4 shows the Identification and Source sections for the New region of the Region Practice page and their properties Title, Type, and Text. The Title property identifies the region and describes its purpose. This value is typically displayed in the region’s header when the page is rendered.

Save and run the page. It should look like Figure 3-5. Note that each title is displayed in the header of its region, in italics, bold, and red, respectively.

A region’s content is determined by its Type property and Source section. The type of a region specifies what kind of content it holds, and the Source section specifies the actual content. For example, if the region’s type is Static Content, then its Source section contains the text the region should display; if a region’s type is Classic Report, then its Source section specifies the table that the region should display.

New regions are assigned the type Static Content, and its source text is empty. For fun, let’s assign some source text to the regions My First Region and My Second Region. I went for something simple, namely, This is my first region and This is my second region.

You change a region’s Type property by selecting a type from its list of possible types. For example, change the type of My Third Region to Classic Report. When you do so, the Source section changes so that you can specify a report; see Figure 3-6. By default, the property editor expects the report to display an entire table: the source type is Table/View and the Table Name property is empty, awaiting the name of a table. The property editor places a red error indicator next to the property name to remind you to enter the table name. It is quite insistent on this point—it will not let you save the page until the error is cleared up. So enter DEPT as the table name, and watch the error icon disappear.

Alternatively, the source of a report can be an SQL query. To try it out, change the source type to SQL Query. This will cause the Table Name property to be replaced with the property SQL Query, again with a red error indicator. Enter the query select * from DEPT and watch the indicator disappear.

Figure 3-7 displays the result of running the revised page.

Layout Section

A region’s Layout section contains properties that specify the location of the region on its page. These properties are shown in Figure 3-8.

The Parent Region and Position properties provide two different ways to specify the region’s location on the page. Only one of these two properties can have a value. A value for Parent Region means that the region should be located within a specified region, called its parent. A value for Position means that the region should be located at a specific position on the page. By default, a new region is located in the Content Body position, as shown in Figure 3-8. You can change the position by selecting from its drop-down list, as shown in Figure 3-9.

These positions are listed in the order they appear on the page, from top to bottom. Most positions have specific purposes. For example, the Content Body position is the primary location for general-purpose regions, the Page Navigation position is intended for the navigation menu along the left side of the page, and the Breadcrumb Bar is for breadcrumb regions.

The set of possible region positions is determined by the page’s template. When a page is created, it is assigned the default template defined by the application’s theme. For example, the default page template for the Universal theme is called Standard.

It is possible to change a page’s template. Select the component for the page in the rendering tree, and look at the Page Template property in the Appearance section. At the moment, the template is set to Theme Default. You can change the template by clicking the property’s select list. For example, change the template for the Region Practice page to Right Side Column, as shown in Figure 3-10.

Now choose a region (say, My Second Region) and reexamine its list of Position values; you will discover that in addition to the values in Figure 3-9, there is also the value Right Column. Set the position of My Second Region to Right Column and rerun the page. That region should now appear as a right sidebar, as shown in Figure 3-11. (I added more text to the source of the second region to make it more sidebar-like.) Note that the sidebar region has an arrow icon at its top left. Clicking the icon toggles between displaying the sidebar and hiding it.

The Layout section also has a property Sequence , which can be seen in Figure 3-8. If two regions are located in the same position on a page, their Sequence value determines the order in which they are placed in that position. Regions are assigned sequence numbers in the order in which they were created, but you can change that order by simply assigning different values to Sequence. For example, the My First Region and My Third Region regions are both located in the Content Body position, with sequence numbers of 10 and 30, respectively. If you change the sequence number of My Third Region to 5, the rendered page will look similar to Figure 3-11, except that My Third Region will appear above My First Region.

Although it is good to experiment with placing regions in various positions on the page, most regions on a page are usually located in the same position (in particular, Content Body). In this case, the remaining properties of the Layout section determine the relative location of the regions within that position.

The Start New Row and New Column properties of the Layout section allow you to specify which option to use. Figure 3-12 displays these properties for a region that is placed in a new column of the same row. Figure 3-8 showed the case when a region begins a new row; note that in this case, the New Column property is unnecessary and thus not present.

After assigning each region to a row and column, APEX then determines the size and location of the regions within the position. To do so, APEX uses the values of the Column and Column Span properties (shown in Figure 3-12) to determine the offset and width of each region in a row.

The Column property specifies the offset of the region within its row. APEX divides the width of a position into 12 “grid points”; the value of Column is a number from 1 to 12, denoting one of those points. A value of 1 specifies that the region begins at the far left of the position; a value of 7 specifies that the region begins in the position’s center. The Column Span property specifies the width of the column. Its value is also a number from 1 to 12, denoting the width in grid points.

For example, Figure 3-13 shows yet another configuration of the Region Practice regions. Here is how you can create that configuration starting from Figure 3-11: Begin by changing the page template back to Theme Default, moving My Second Region back to the Content Body position with the others, and changing the sequence number of My Third Region to be the smallest. Then set their Grid properties as follows:

• My Third Region starts a new row, its Column value is 3, and Column Span value is 8. That is, its width is two-thirds the size of the position and centered.

• My First Region starts a new row, its Column value is 1, and the Column Span value is 4. Thus, its width is one-third the size of the position and left justified.

• My Second Region does not start a new row. Its Column value is 9, and the Column Span value is 4. Thus, its width is also one-third the size of the position, but right justified.

If you do not need such fine control over the placement of the regions in a row, you can assign the Automatic value to their Column and Column Span properties (as in Figure 3-8). In this case, APEX will place the regions in the row according to its best judgment.

Appearance Section

Figure 3-10 showed the Appearance section for a page, whose properties allow you to configure the page’s template. Similarly, each region also has a template, which is specified by the Template property in the region’s Appearance section . Figure 3-14 shows the various values for this property.

The Standard template , which is the most common, displays the region’s title in a border across the top. Many of the other templates have special purposes, such as Alert, Inline Dialog, Login, Title Bar, and Wizard Container.

The Collapsible template is similar to Standard , with the addition of a small button in the top-left corner. Clicking the button toggles between hiding the body of the region and displaying it. A region using the Buttons Container or Blank with Attributes template is untitled; the main difference between these templates is that a button region has a border, whereas a blank region does not.

Formatted vs. Unformatted Text

The source of a static content region is the text to be displayed. APEX can interpret this text in two ways: as the characters exactly as written or as HTML code to be formatted. The property that specifies this option is called Output As, and it appears in the Settings section of the region’s Attributes node in the page rendering tree. Figure 3-19 shows this section with the two possible values of the Output As property.

An Output As value of HTML specifies that the region’s source contains HTML code. APEX will send this code as-is to the browser when it renders the page, so that the browser can format the source accordingly.

On the other hand, a value of Text (escape special characters) specifies that the source should be displayed exactly as it appears. In this case, APEX needs to transform the text so that there are no HTML tags for the browser to execute. It does so by replacing certain characters (such as < and >) with different characters that happen to print the same (such as < and >). This transformation is called escaping the characters. The result is text that looks like HTML code, but really is not.

The beginning of this listing makes reference to “&APP_USER.”. This string is called a substitution string, and APEX interprets it as the name of the user. This topic is addressed next.

Substitution Strings

To refer to the value of a variable from within HTML text, you prepend the character & and append the period character (.) to the variable name. Such an expression is called a substitution string. In other words, the substitution string for a variable named X is written “&X.” . When the APEX server renders a page, it textually replaces the substitution string by the value of its variable.

For example, the substitution string &APP_USER. appears in the source of the Demo Application region. When the APEX server renders the page, it textually replaces the substitution string with the value of the variable APP_USER, which in this case is [email protected].

Referring to APEX Pages

The HTML <a> tag specifies a link; its argument is the URL of the target location. The first link in the listing is a typical link, which refers to a page on an external website. The second link refers to a page of another APEX application—in particular, page 1 of application 100 on the APEX server at asktom.oracle.com. Note how the link uses the “f?p=” notation, as described in Chapter 2.

The concept of a session will be covered in Chapter 6. For the moment, it suffices to know that APEX uses a session identifier to indicate related page accesses. By passing the current session ID into the URL, you ensure that the current session will continue when the link is followed. Note that the second link in the region did not include a session identifier. This was appropriate because the link was beginning a new session with the Ask Tom application.

Referring to Local Images

An HTML <img> tag displays an image; its argument is the URL of the image file. If the URL is a reference to a file on another web server, an absolute URL works fine. However, if you plan to store an image file on the APEX web server, then you should use a relative URL. The format of this URL is determined as follows.

The first thing to do is upload the file to the server. Go to the home screen of your application, click the Shared Components button, and find the Files section as shown in Figure 3-20.

You have two options to choose from: Static Application Files or Static Workspace Files. The difference between them is one of visibility. An application file can be referenced from a specific application only, whereas a workspace file can be accessed by any application in the workspace. Whichever option you click, you will be taken to a screen that lets you choose your file. Then click the Upload button to upload it.

Note the two different uses of the period character in this tag. The first one is part of the substitution string notation and will be replaced by the path to the image directory when the page is rendered; the second one is part of the filename.

This code uses the <img> tag to display the employees.jpg image and then uses <a> and </a> tags to wrap this image in a link. Consequently, clicking the image takes the user to page 3 of the application (which means that the link will be nonfunctional until the next section, in which page 3 is created).

Chapter 2 discussed the possibility of using an image as the application’s logo. To demonstrate this possibility, I created a stylized image of the words “Employee Demo,” saved it in the file Logo.jpg, and uploaded it to APEX as an application file. I then configured the application’s logo as described in Chapter 2. That is, I clicked the Edit Application Properties button in the application home page, clicked the User Interface tab, and modified the properties in the Logo section, as shown in Figure 3-21. A screenshot of the logo appears in Figure 3-22.

Column-Specific Properties

Each column in a report has its own set of properties. When you select a column node in the rendering tree, the property editor shows you its column-specific properties. These properties are grouped into several sections, which are discussed next.

Identification

Figure 3-26 displays the two properties in the Identification section. The Column Name property is the name of the column. The column name comes directly from the source query, and therefore this value cannot be changed.

The Type property specifies how APEX should display the column values. The possible type values are shown in Figure 3-26. The type Plain Text is the default and says to display the value as is. The type Link says to display the value as a link, the type Display Image as an image, and the type Percent Graph graphically. The type Hidden Column says not to display the values at all.

In the Default Report region, all columns are plain text. The columns of the Formatted Report region have the following types: ENAME, SAL, and OFFSITE are plain text, EMPNO and JOB are hidden, HIREDATE is a link, and DEPTNO is plain text based on a list of values. In your application, you can change the type of the two hidden columns now. However, you need to wait until later in the chapter before you can change the type of HIREDATE and DEPTNO.

Column Heading

A column’s Heading section contains two properties for customizing the column’s report header. The Heading property contains the value that is displayed in the column header. By default, this is the column name, but it can be changed. For example in my application, I changed the header for ENAME to be Name and the header for DEPTNO to be Department.

In general, the value for Heading can include HTML code, such as formatted text or an image. For example, Figure 3-27 shows my HTML code for the header of HIREDATE, which causes APEX to display the string Hiredate in italics.

By default, column headings are aligned in the center of the column. This is almost always what you want. However, the Alignment property lets you specify a different alignment if for some reason this seems appropriate.

Column Layout

The Layout section contains two properties for customizing the display of the columns. The Sequence property determines the order in which the columns appear in the report. The Column Alignment property specifies the alignment of the column values. By default, column values are aligned to the left. Figure 3-28 shows the Layout section for the SAL column, in which the alignment is set to the right.

Sort Order

APEX divides the issue of sorting into two aspects: how it sorts the records when it first renders the report and whether the user can interactively re-sort the report by clicking column headers. If a report’s source query has an order by clause, the records are sorted in that order and cannot be altered by the user. Otherwise, these aspects are determined by the properties in each column’s Sorting section. Figure 3-29 shows the Sorting section for ENAME.

The Default Sequence property specifies the initial sort order. Each column that participates in the initial sort order will have a value for Default Sequence, with the primary sort column having value 1. In Figure 3-29, ENAME has sequence 2. Not shown is the sequence property for JOB, which has sort sequence 1. Together, they imply that the report will be rendered with the rows sorted by job, and two employees having the same job will be listed alphabetically by name (as you can see in Figure 3-24).

The Sortable property specifies whether a user is able to interactively sort on the column. By default, all columns are sortable. In the Formatted Report region, I turned off sortability for all columns except ENAME and SAL.

The initial sort sequence is completely independent of sortability. For example, the Formatted Report region is initially sorted by the JOB column, even though the column is not even visible.

List of Values

Consider the DEPTNO column in the formatted report. It displays values from the DEPT table, even though the report mentions only the EMP table. How can this be?

The answer is that the values in the column have not changed; they are still department numbers. However, you can set up a correspondence between department names and numbers and tell APEX to display the name corresponding to a given department number. This correspondence between the return value (the department number) and its display value (the department name) is called a list of values.

Formally, a list of values is a two-column table. The first column holds the display values, and the second column holds the corresponding return values. One useful way to specify a list of values is to use an SQL query. For example, the list-of-values query for the DEPTNO column is simply this:

select DName, DeptNo

from DEPT

When you assign a column to have the type Plain Text (based on List of Values), the property editor displays a List of Values section. Figure 3-30 shows the section with the property values filled in.

Format Masks

You occasionally might want to display a number as a string having a particular format. For example, you might use a comma to separate every three digits, you might have a prescribed number of digits to the right of the decimal point, or you might prefix the number with a currency character. Date values can also be written in different formats. In each case, you can use a format mask to express your desired format.

A column's Format Mask property is in its Appearance section. Figure 3-31 shows how I filled in the property for SAL. The icon to the right is a “quick pick” button. Clicking it brings up a list of common formats; selecting a format places its mask in the property’s text box. If you are not familiar with the Oracle format mask syntax, you can get a reasonable understanding by examining the various masks. For example, 9 denotes an optional digit, 0 a required digit, G a thousands’ separator, D the decimal point, and so on. Such an understanding makes it possible to modify the mask to fit your needs.

For example, to get the mask for the SAL column, I chose the currency format $5,234.10 from the format list, which produced the mask FML999G999G999G999G990D00. However, because the EMP table stores salary values in whole dollars, I did not want to display the decimal point and the two digits to its right. So I removed the D00 from the end of the mask.

The mask for HIREDATE was created similarly. An examination of the various date format masks shows that DD denotes the day, Mon the three-character abbreviation of the month, and YYYY the four-digit year. I combined these elements to create my desired format mask, which is shown in Figure 3-32.

For a complete description of format mask syntax, search the Oracle SQL documentation for “format models.”

Column Formatting

Columns of type Plain Text have a section called Column Formatting, which has a property named HTML Expression . This property allows you to format a column value by wrapping it in an HTML expression. For an example, look back at the formatted ENAME column of Figure 3-24. The name of each employee is in a large bold font, and the employee’s job appears after it. Figure 3-33 shows the HTML expression corresponding to this format.

This expression requires some explanation. To begin, consider what HTML expression you would write for the employee named FORD. To make the name large and bold, you can place it inside <span> tags. The resulting expression would look like this:

<span style="font-size:150%;

             font-weight:bold">FORD</span> the ANALYST

This expression is almost what the HTML Expression value should be—the only difference is that the employee’s name and job need to vary for each row of the report. APEX makes this possible via the following convention: for a column named X, the term #X# denotes the value of X in the current row. Thus, you should replace FORD in the preceding expression by #ENAME# and ANALYST by #JOB#, resulting in the expression from Figure 3-33:

<span style="font-size:150%;

             font-weight:bold">#ENAME#</span> the #JOB#

Note that the expression #JOB# makes sense, even though the JOB column is not visible in the report. In fact, one of the common reasons for having nonvisible columns in a report is so you can use their values elsewhere in the report.

Link Columns

The HireDate values in Figure 3-24 are formatted as links. In particular, clicking a hire date (say, Dec 03, 1981) redirects the browser to the URL http://www.infoplease.com/year/1981.html, which gives the current events of that year.

One way to implement this functionality is to wrap the hire date in an appropriate HTML expression. For example, the link for Dec 03, 1981, would be the following:

<a href="http://www.infoplease.com/year/1981.html"

   target="_blank">#HIREDATE#</a>

Note that the second argument to the <a> tag is target="_blank". This argument causes the target page to open in a new browser tab, which in this case seems reasonable.

The problem with this HTML expression is that it always redirects to the page for 1981, regardless of the hire date. We need a way to extract the hire year from the hire date, which unfortunately is not possible in HTML.

However, it is possible to extract the year from within an SQL query. The idea is to have the SQL source query compute a new column, whose value is the hire year. The following query does the job:

select e.*, extract(year from e.HireDate) as HireYear

from EMP e

A consequence of using this new source query is that HIREYEAR will now be a column of the report. Since you don’t want to see it in the report, you should set its type to Hidden Column.

After you modify the source of the Formatted Report region to be this query, you can format the HIREDATE column by using #HIREYEAR# in its HTML Expression property, as follows:

<a href="http://www.infoplease.com/year/#HIREYEAR#.html"

   target="_blank">#HIREDATE#</a>

Although this technique works, a better way to format a column as a link is to set its Type property to Link. Doing so causes the property editor to display a Link section. This section has the property Target, whose initial value is No Link Defined. Clicking that value opens a modal Link Builder page, in which you specify whether the target is a page of an APEX application or an arbitrary URL. In this case, select URL and enter the target URL into the text box that appears, as shown in Figure 3-34. Then click the OK button to return to the property editor.

You can then enter the appropriate values for Link Text and Link Attributes into the Link section, as shown in Figure 3-35. Note that you need to enter the “http://” portion of the URL in the link builder, even though the Target property does not display it.

Report-Specific Properties

It is now time to consider the report-specific properties of a classic report. These properties are associated with the region’s Attributes node in the rendering tree and handle issues such as pagination and record grouping. Figure 3-36 shows the Layout and Pagination sections for the Formatted Report region.

The Number of Rows property specifies how many rows of the report to display at a time. By default, the value is 15, but I changed it to 5 in the Formatted Report region. The pagination Type property allows you to select the format of the pagination controls. The option shown in the figure was used for the Formatted Report region in Figure 3-24. The best way to understand the other options is to try each one on your report to see its effect.

Using the Source Query for Formatting

Although the previous sections have focused on how to use APEX to format the rows of a source query, it is important to realize that you can get many of these same features by using a more precise source query. Here are some examples for the Formatted Report demo region.

Instead of hiding a column, it might be more appropriate to simply not include it in the query. In particular, the EmpNo column serves no purpose in the formatted report and is better off being left out of its source query entirely. On the other hand, the columns Job, SalColor, OffsiteImage, and HireYear are needed for the formatting of other columns, so they must appear in the source query and therefore must be of type Hidden Column.

If you don’t want the user to be able to change the sort order of the records interactively, it is easier to specify the sort order in the source query than to set the sortability property of each column individually.

In this case, it is hard to say which of these two approaches is better than the other. The list-of-values approach requires that APEX search the list of values for each row of the report, which is potentially more expensive than simply doing the join in one shot. On the other hand, the list-of-values approach is simpler and more directly conveys the intent of the designer.

The rule of thumb is that the source query should specify what you want displayed, whereas the column properties should specify how you want them displayed. In some cases (such as hidden columns), this distinction is clear. In others (such as using a list of values), it is less so.

Creating a Chart Region

To build this page, begin by creating a new blank page named Charts, and add to it two regions of type Chart. Name the first region Salary Info and the second region Employee Counts. Figure 3-39 shows the resulting rendering tree for these regions.

From this figure, you can see that a chart has four kinds of properties: type-independent properties (denoted by the region name), chart-specific properties (denoted by Attributes), properties specific to each chart series (denoted by Series), and properties associated with the chart axes (denoted by Axes). By default, a chart is created with one series (named New), but you can rename the series and add others.

Each series in Figure 3-39 is flagged with a red error indicator to tell you that the chart needs further configuration. Details of this configuration are discussed next.

Configuring a Chart

You specify the source of a chart similar to how you would specify the source of a report. The chart’s Source section contains the three properties you need. Figure 3-40 shows the values of these properties for the Salary info region. You should also make similar changes to your Employee Counts region, using the following source query:

select Job, count(*) as EmpCount

from EMP

group by Job

order by EmpCount desc

Configuring a Chart Series

After you have configured the source of a chart, you can configure each of its series. The relevant properties for a series are in its Identification, Source, and Column Mapping sections. Figure 3-41 shows these sections for the series created for Salary Info.

The Identification section allows you to choose a name for the series. Because this series will hold the minimum salaries per job, I named it MinSal. (You will also need to create another series to hold the maximum salaries, but not yet.)

The Source section is where you specify the source of the series. Since you have already defined a source for the region, you should choose Region Source. Your other option, not discussed here, is to have each series define its own source. This flexibility is useful in situations where you are comparing data from different tables, but leads to complexity beyond the scope of this book.

The Column Mapping section requires you to specify values for the properties Label and Value. The Label value will be the name of the source column that holds the labels, in this case JOB. The Value value will be the name of the source column holding the values for this series, in this case MINSAL.

After configuring the Salary Info series, you should configure the series for the Salary Info chart, using Figure 3-41 as a model. When you are done, the error indicators should have disappeared from your page and you should be able to save it. If you run the page, you should get the output shown in Figure 3-42. These charts are pretty good, but are in need of customization. This topic is discussed next.

Customizing a Chart

APEX supports several chart types. The default type of a new chart is a bar chart, but you can use the Chart section (from the Attributes component of the rendering tree) to change it. For example, go to the Chart section of your Employee Counts region and change its chart type to Pie.

APEX automatically assigns a color to each series in a bar chart. It does a reasonable job of choosing chart colors, but sometimes you want to choose your own. Each bar chart series has a Color property in its Appearance section, as shown in Figure 3-45. You can type the name of a standard color (such as “maroon”), you can choose a common color from the quick-pick menu on the right, or you can use the color picker to choose a color from the color wheel. The Salary Info chart of Figure 3-37 specified the series colors MAROON and GOLD.

APEX also assigns a color to each label value of a pie chart, using a palette of bright colors. But suppose you want a different palette. It’s not immediately clear how to use the Color property in Figure 3-45, because it applies to the entire series. For example, if you set the color to MAROON, then every segment in the pie chart would be maroon. What you need is a way to specify a color for each label.

The JobColor column calculates a color for each job. The specified color values correspond to the blue palette shown in Figure 3-38. Figure 3-46 shows the revised Source section for the Salary Info chart.

The value of JobColor can be used in the Color property, as shown in Figure 3-47. Note how the reference to JobColor is written as a substitution string.

Another way to customize a chart is to display a legend. For example, Figure 3-37 displays a legend underneath the chart. A legend explains the meaning of each color on the chart. Multi-series charts use legends to convey the meaning of each series. Pie charts use legends to identify the segments. Consequently, Figure 3-38 does not need a legend because the label values are displayed directly with each segment.

In APEX, the properties to specify the legend are in the Legend section, which belongs to the region’s Attributes node. Figure 3-48 shows the top part of this section.

The most important property is Show, which toggles the visibility of the legend on the page. It usually suffices to use the default value for the other properties, although you should try out the options to see what happens. Especially notable is Hide and Show Behavior. If its value is None, then clicking the legend does nothing. Otherwise, clicking a series name on the legend toggles the visibility of that series in the chart and recomputes the chart accordingly. This behavior is especially interesting for a pie chart, where the legend identifies slices instead of series. As an experiment, enable the legend of the Salary Info chart and set the Hide and Show Behavior value to Rescale. Then run the page, click some legend values, and watch the chart adjust itself.

Another chart customization is to explicitly display data values in the chart. For example, in Figure 3-37, the min and max salaries are displayed above its bar. And in Figure 3-38, the employee count and label name are displayed outside each segment. The relevant properties are in the Label section of the series properties. Figure 3-49 shows how I filled the properties for the pie chart.

Finally, I would like to briefly mention the properties governing the x and y axes for bar charts. These properties concern how the axes are displayed—how often to display a tick mark, how to format the displayed values, what the range of y values are, and so on. Often, the default values suffice, but occasionally customization is required. One example can be found in the Employee Counts chart from Figure 3-42. Note that its y-axis labels contain duplication. The reason is that the grid markings go up by 0.5, but the labels are displayed as integers only. This situation is depicted in Figures 3-50 and 3-51.

The Decimal Places property in Figure 3-50 has the value 0, meaning that APEX will display y-axis labels as integers. If you change the value of Decimal Places to 1, then you will see the y-axis labels actually have the value 0.0, 0.5, 1.0, and so on. However, such a chart doesn’t make any sense because counts must be integers. A better solution is to change the Minimum Step property in Figure 3-51. This property tells APEX how close the ticks can be. By default, the value is blank, which allows APEX to choose any step value. You need to set the property value to 1, so that the y-axis labels have the values 0, 1, 2, and so on.

APEX has many chart-configuration properties. The best way to understand them is to experiment. Edit the two charts by changing their properties in various ways. For example, move the legend around, change the color scheme and background, include or remove labels or values on the chart, and so on.

Using the Search Bar

The search bar contains four items: the magnifying glass, text box, Go button, and Actions button. The first three items let a user filter the rows of the report. The user enters a search string in the box, clicks the magnifying glass to choose the column to search (All Columns can also be chosen), and clicks Go. The records not containing the search text will be filtered from the report.

For example, entering 82 in the text box and selecting the column Hiredate has the effect of filtering for all employees hired in 1982. Figure 3-53 shows the resulting region.

Note that the region now has a row below the search bar that describes the filter. You can click the checkbox on the left to enable/disable it, or you can click the X on the right to permanently remove it.

It is possible to have multiple concurrent filters. For example, to find employees hired in 1982 who work offsite, you would need to add another filter for the Offsite column. The result is shown in Figure 3-54.

In general, a user can explore the contents of a report by creating multiple filters and selectively enabling various subsets of them.

The Actions button allows a user to further customize the report. Clicking the button displays its menu of possible operations. This menu appears in Figure 3-55, showing the submenu for the Data action. The following sections describe the more useful of these operations.

Columns

Choosing the Columns operation brings up a modal dialog box that lets the user choose the columns to be displayed in the report and in what order; Figure 3-56 illustrates an example that selects the columns Ename, Job, Hiredate, and Sal for display.

Filter

Choosing the Filter operation brings up a modal dialog box that lets the user create a filter; see Figure 3-57. It produces filters similar to the filters you created for Figures 3-53 and 3-54. The difference is that those earlier filters could check only for text containment, whereas this dialog box allows for many kinds of operations. For example, the filter specified in Figure 3-57 is Job!='CLERK'.

Sort

Choosing the Sort operation brings up a modal dialog box that lets the user choose the desired sort order; see Figure 3-58. The user selects the column(s) to be sorted and whether the sort direction is ascending or descending. The figure shows the menu to select a sort column. Note that the user can sort on both visible and hidden columns.

Highlight

The Highlight operation is in the Format submenu. It allows the user to highlight rows or cells that satisfy a specified criterion. Recall that the formatted classic report of Figure 3-24 displayed high salary values in red. This is a form of highlighting. The Highlight operation allows the user to express this and other forms of highlighting easily.

Choosing the Highlight option brings up the modal dialog box of Figure 3-59. The Highlight Condition values specify the values of interest. If the value of Highlight Type is Cell, those values are highlighted; if it is Row, the row containing those values is highlighted. Highlighting can involve the background color, text color, or both. The figure shows the highlighting corresponding to Figure 3-24.

Rows Per Page

The Rows Per Page operation is also in the Format submeu. It allows the user to change the report pagination at will. Clicking the menu item displays a submenu in which the user can choose from a list of possible rows per page.

Chart

Choosing the Chart operation brings up a modal dialog box that lets the user create charts based on the data in the report; see Figure 3-60.

From this dialog box, a user can create a single-series chart that aggregates over a single column. The figure specifies a bar chart that gives the minimum salary per job, similar to the bar chart shown in Figure 3-37. The resulting chart appears in Figure 3-61.

There are two things worth noting in this figure. First, many aspects of the chart are not customizable. For example, a chart can have only a single series and the color palette is fixed. Second, the search bar has been extended to include two report/chart buttons to the left of the Action button. The user can use these buttons to toggle between the interactive report and its chart.

Configuring the Search Bar

The search bar has a lot of functionality. However, not all applications need all the functionality. An interactive report region has properties that allow the application developer to limit this functionality. This section examines those properties.

Figure 3-62 shows the rendering tree for the Interactive Reports page and its interactive report region Employees. Note that this tree has the same structure as a classic report (refer to Figure 3-25), namely, that the Attributes component contains the report-specific properties and the Columns folder contains the properties for each column.

The property editor for the Attributes node contains two relevant sections: Search Bar and Actions Menu. Figure 3-63 shows the properties of the Search Bar section. These properties let you selectively display different portions of the search area. For example, turning off the Include Search Bar property completely disables the bar, turning off the Search Field enables only the Action button, and so on.

Figure 3-64 shows the first several properties of the Actions Menu section. These properties let you specify which operations are displayed in the menu. (Not all the properties are shown due to lack of space.)

Finally, each column of an interactive report has properties for configuring its specific capabilities. These properties appear in the Enable Users To section of that column and are shown in Figure 3-65. (Again, not all properties are shown because of lack of space.)

Link Column

An interactive report can display a special column, whose value is a link. Clicking this link shows the report in single row view. That is, the report changes to show the values of only that row; it also displays navigation buttons for the user to move to the next or previous row and a button to return to the original report. Figure 3-66 shows the interactive report with the link column displayed. Figure 3-67 shows the single row view of the report after the link for BLAKE is clicked. Note that this single row view displays all the columns, not just the ones displayed in the report.

The property editor for the region’s Attributes component has two sections—Link and Single Row View—that let you enable the link column and configure its behavior. The properties for the Link section appear in Figure 3-68.

To enable the link column, set the value of the Link Column property to Link to Single Row View. (You can also set it to link to an arbitrary URL, but this choice is less interesting.) You then have to specify which row is to be selected when the link is clicked. The value ROWID says to use the row that was clicked, which is the most natural.

Figure 3-69 shows the Single Row View section. The interesting property here is Only Displayed Columns: turning it on specifies that the single row view should display the same columns as the report; turning it off specifies that it should display all the columns.