Tools Guide


Chapter 4   View Designer

The SilverStream View Designer enables you to create Java-based programmable view controls. These controls are data-bound and can be used to display data in a tabular (rows and columns) or hierarchical (master/detail) format.

This page describes the following:

About the View Designer   Top of page

The View Designer is a tool that you use to graphically construct and test view controls (instances of the AgcViewDownloadable class). You define the structure and data bindings of the view by choosing fields from one or more related database tables; you define the appearance of the view by setting its properties. When you save or test the view, SilverStream generates an instance of the AgcViewDownloadable class whose physical appearance and data bindings are constructed based on your selections.

You can use the View Designer to:

Tabular and hierarchical views

You can use the View Designer to create a tabular (single-level) view or a hierarchical view (master/detail). Both types of views require that you specify a primary table. The primary table is, by default, the table whose fields you select first. When you select fields from a single table, or from multiple tables where the relationship to the primary table is one-to-one or many-to-one, the designer creates a single-level view. If the fields that you select are from multiple tables where the relationship to the primary table is many-to-one, the designer creates a hierarchical view. For example, you can construct a view that not only includes a list of customers but also all the orders placed by those customers, along with total sales figures for a particular quarter.

View components

Views are compound objects. They are composed of the following elements:

Component

Description

Header band

A specialized band that is a collection of one or more column headings. The heading can be a static text string, a value from the database or an expression.

Data band

A collection of fields from a primary table, fields from tables related to the primary table or computed columns. The band represents the actual data row returned from a query.

Every band in a view must have a primary table. Each view has one or more data bands.

Column

A column represents all of the values of a particular database field in all of the rows.

A band consists of one or more columns.

Footer band

A specialized band. Like the header band it can contain static text strings, a value from the database or an expression. Footer bands are optional.

The following shows the header and data bands in a tabular or single-level view.

A hierarchical view contains all of the same components as a single-level view plus:

Component

Description

Master band

The data band of the primary table.

Subband

Bands that are related to the primary table band in a one-to-many relationship appear in the view as subbands.

Each subband can have a header and footer band.

The following shows these additional elements in a hierarchical view.

You might think of the View as the container for its bands and the band as the container for its columns.

Types of view controls

SilverStream provides two types of Java-based view controls: AgcViewDownloadable and AgcView (the parent class). Both controls are composed of bands, columns and data. The primary difference is that you use the View Designer to generate the AgcViewDownloadable class while you construct each component of an AgcView control programmatically.

Since you build AgcView controls programmatically you have more knowledge of how each component is named and constructed. When you generate a view using the View Designer, SilverStream creates and manages each component for you. You do however, have programmatic access to each of AgcViewDownloadable components where you can modify its runtime appearance and behavior.

    For more information about programmatically modifying an AgcViewDownloadable control, see the chapter on Java-based views in the Programmer's Guide.

Deploying views

Views constructed using the View Designer are available in the Form and Page Designer environments by choosing the Views icon in the gallery. You can deploy a generated view by dragging and dropping it onto the desired form or page. When you deploy a generated view in one of these environments, SilverStream links the data bindings of the view to the data bindings of the form or page that hosts it so that the data is linked to the form or page's agData or to some other data-bound control.

    For more information on including views in a form, see the chapter on forms in the online Tools Guide.

About properties   Top of page

In the View Designer, you can use the Property Inspector to specify some of the view's runtime attributes. Each component of the view, the columns, bands, and view, has properties associated with it. The view component properties are described in the following sections. You can override some of these values or set additional properties once you have dropped the view onto a form or page. See the API Reference for definitions of those properties.

You should also note that views as compound objects are made up of layers. If you set a property, like transparency or color, on the View (the lowest layer), you must also set the corresponding property on the bands and columns (top layer) to achieve the desired effect.

View properties

The following table describes the properties that you can set on views.

Property

Description

Background color

Specifies the view's background color. To see this background color, the data, header, and footer bands and all columns must be transparent.

Transparent

Enables or disables the view's transparency.

Caret color

Specifies the color used to highlight the currenlty selected row.

Background image

Specifies the database, file, or URL of an image to display as the view's background.

To see the background image, the data, header, and footer bands and all columns must be transparent.

Multiple row selection

Enables or disables the ability to select multiple rows simultaneously.

Tool tip

Specifies the text that should be displayed to the user as a tool tip.

Help page

Specifies an HTML file that contains help text associated with the control. The Help Page can either be the name of a page in the application's database, the name of a page in a different database (database:pagename), or a full URL to a help page.

When the user presses F1 while the control has focus, SilverStream opens a new browser window and displays this page.

If no Help Page is specified and the user presses the F1 key, then the containing control is searched for a Help Page to display. If the containing control does not have a Help Paage, then the next containing control is searched, and so on until either a Help Page is found or the form is reached.

A browser is opened only if a Help Page is defined.

Band properties

The following table describes the properties that you can set on bands

Component

Description

Band name

The name of the band.

You manipulate the band programmatically using this name.

Base table

The name of the database table to which this band is bound.

Show header

Specifies when to display the header band.

Show footer

Specifies when to display the footer band.

Indent

Specifies the number of pixels that the column text is indented.

Background color

Specifies the band's background color. If the Transparent property is false(unchecked), the band's background color is not visible.

Transparent

Enables or disables the band's transparency.

Where clause

Specifies the criteria or conditions that must be met in order for a record to be included in the view's dataset.

SilverStream appends the Where keyword to the SQL String so it is not necessary to enter it in the Property Inspector.

Distinct

Specifies that only unique rows should be returned to the view.

Limit number of returned rows

Indicates that only the number of rows specified by the Maximum rows property should be returned to the view.

The rows are returned in the order specified by the Order by property (if specified) or in a random order as they are found by the database server.

This property limits the number of rows returned to the actual number specified, if you wanted to get the next 10 rows, you would have to programmatically requery the database.

Maximum rows

The maximum number of rows to return to the view when the Limit number of returned rows property is true.

Order by

Specifies which column of the view to sort on. The field that you select must exist in the view or SilverStream generates an error.

Column border

Specifies the border appearance for all of the columns in the band.

Column properties

The following table describes the properties that you can set on columns.

Component

Description

Name

The name of the column. You can manipulate columns programmatically by this name.

Type

Defines the type of data or behavior of the column. Types include:

  • Text. Use to displays any type of read-only data.

  • Text editor. Use to allow the user to edit the field. Changes that the user makes are updated to the database programmatically by calling updateRows().

  • Hierarchy. Use for displaying hierarchical relationships. The columns bound to the fields involved in the primary key/foreign key relationship must be defined as hierarchy columns.

  • Image. Use to display images from a database, the file system or an URL.

  • Spacer. Use to create fixed width space between columns.

Visible

Enables or disables the column's visibility. When checked, the column is visible.

Width

Specifies the column's initial pixel width.

Users can resize columns.

Background color

Specifies the column's background color.

Transparent

Enables or disables the column's transparency.

Value

Specifies the value to display for the column. It can be a static string, an expression, or a database column.

Font

Specifies the attributes of the column's text font.

Text alignment

Specifies how the text or image is aligned within the column.

Multi-line

Enables or disables word-wrap on the column.

If disabled and a text line does not fit the column, the text is clipped.

Keyboard shortcuts   Top of page

While in the View Designer, you can use these keyboard shortcuts:

Keystroke

Description

Ctrl+S

Save

Ctrl+Z

Undo

Ctrl+Y

Redo

Ctrl+X

Cut

Ctrl+C

Copy

Ctrl+V

Paste

Ctrl+G

Goto line number

Ctrl+F

Find/Replace

Ctrl+T

Test

F1

Help

F3

Find again

F4

Property Inspector

Creating views   Top of page

This section describes how to create a view. It describes how to do the following:

To create a view using the View Wizard:

  1. Select the database you want to use with your view from the SilverStream Designer. To see a list of resources associated with the database, select the plus sign that appears next to the icon.

  2. Select the Views icon from the list. A list of existing views appears in the right pane.

  3. Select the New icon from the action gallery that appears at the bottom of the right pane of the main window. The first View Designer Wizard window appears automatically.

  4. Select the table you want to use as the primary source of data for your view. Choose Next>. The Relational Data Palette appears.

  5. Select the columns you want to include in your view. Fields that are related to the primary table in a many to one relationship appear in your view as a band.

  6. Select Next> when you are through picking columns.

  7. Select a style for your view. The style types appear in the list box on the left side of the window. As you scroll through them, the sample view on the right side of the window changes so you can preview the styles before you select one.

  8. Choose Next> when you determine your view style. The View Wizard Summary window appears. The View Designer Wizard automatically assigns the name of the primary table as the name of the view.

  9. Select Finish. The Wizard generates the view, saves it to the server, and displays it in the View Designer.

The first column of the view shows the band name you specified along with the name of the primary table for that band.

To create a view manually:

  1. When the first View Designer Wizard window appears, select Cancel to go directly to the View Designer window.

  2. Select the Data icon from the View Designer toolbar to select the columns you want to include in your view. A list box appears.

  3. To see a list of the tables associated with the database, select the down arrow. Highlight the table you want to use. A list of columns appears. Highlight the fields you want to use and drag and drop them onto your view.

  4. You can add bands or columns to your view by selecting the appropriate button from the View Designer toolbar. A blank column or band appears in your view.

To create a multi-table view:

You can create a view with multiple data layers to provide users with a detailed data view. You can create a multiple table view using either the View Designer or the View Wizard. The following procedure describes how to create a multiple-table view using the View Wizard.

  1. To select another table that is related to the primary table in the View Wizard, scroll all the way down the list of tables in the data palette. Tables related to the primary table appear at the end of the list.

  2. Select a one-to-many relationship to create a detail layer to your view. To see a list of columns for that table, select the plus sign that appears next to the table icon. You can select data from as many different tables as you like.

  3. When you finish picking data, select Finish. The View Wizard names the view, saves it to the database, and displays it in the View Designer window.

  4. To see what your view looks like, select the Test button from the View Designer toolbar. Your view appears, populated with the data you selected. The bands appear preceded by a plus sign. To see the detail data, select the plus sign.

To test a view:

  1. Select the Test button from the View Designer toolbar to activate Test mode. The button changes to the Revert to Design mode button. Your view displays the data you selected.

  2. Select the Revert to Design mode button to return to Design mode and make any changes necessary to your view.

Modifying views   Top of page

Once you have created a view, it is easy to modify or refine it. When you modify and save a view, the class is recompiled. Any references to that view on a form or page will get the updated form of the view, the next time that you save and recompile the form or page. The remaining sections describe how to make some common modifications to views using the View Designer. including:

Changing the view's appearance   Top of page

Resizing columns

Resize a column by dragging its border with the mouse. Changes you make in design mode are saved with the view. Changes you make in test mode are not saved with the view. (Users can also resize columns at runtime.)

Adding a footer

You might want summary statistics to appear in the footer of the view. To display a footer, display the Band tab of the Properties dialog and select Always or With data for Show footer. Typically, you will create an aggregate expression in the footer to summarize the contents of a column. For more information, see Creating aggregates.

Adding bands or columns

You can add bands or columns to your view by selecting the appropriate button from the View Designer toolbar. A blank column or band appears in your view at the current cursor location.

Button

Description

Inserts a text field column.

Inserts a text editor field column.

Inserts a column containing a hierarchy field. These fields are read-only. They are required for hierarchical relationships.

Inserts a column containing an image field. These fields are read-only.

Inserts a column containing a spacer field.

Inserts a band; select the table that is related to the primary table

Changing the view's data   Top of page

Sorting records

Specify an Order by column. The Order by can only include fields that are in the view's definition. If you need to sort by a column that is not part of the view's dataset, you can add the column and make it invisible. However, this might impact performance because more data will be retrieved and returned to the view.

Restricting the number of retrieved rows

You can specify an upper limit for the number of rows returned to the view by setting this value in the Property Inspector or specifying that only unique records should be retrieved by enabling the Distinct property.

Formatting data

You can specify how you want data displayed in the view columns associated with database columns. The View Designer provides several named formats, plus it allows you to specify patterns of characters.

    For information on the formats, including the patterns you can specify in formats, see the expressions page in the Reference online help.

Refining the query

By default, all rows will be retrieved from the database and sent to the client. If you have large tables, you will want to specify a query that restricts which rows are retrieved. For more information, see Building queries.

A simple way to refine the query is to specify a Where Clause using the Property Inspector.

Creating aggregates

An aggregate is a function that you can perform on data in a view. You can put aggregates in headers, footers, or columns in your view.

Be sure that you put your aggregate in a separate column, header, or footer. You cannot put the aggregate in the same column, header, or footer that contains the data you used to create the aggregate.

To create an aggregate:

  1. Create a view or select an existing a view.

  2. Select the column, header, or footer that you want to contain an aggregate.

  3. Access the Property Inspector by either pressing the right mouse button or by selecting the Property Inspector button from the toolbar. The Property Inspector appears.

  4. Select the property sheet for the header, footer or band where you are putting the aggregate.

  5. Select the ellipses in the Value field to access the Expression Builder.

        For more information, see Expression Builder.

  6. Select the variables for your aggregate from the Variables field by highlighting the variable and double-clicking on it. The base table and any referenced columns and bands appear in this field. The variable appears in the Value field.

    NOTE   The variables listed in the Variable field change, depending on where the column, header, or footer you selected is located.

  7. Select the function that you want the expression to perform on the operand from the Operators field.

  8. Select the plus sign that appears next to Aggregation in the Function field. A list of aggregate functions appears.

  9. Select an aggregate function. You can then return to the Variable field to select another variable to include in your aggregate function.

  10. Select Verify to test your expression. If it is incorrect, an error message appears indicating where the problem is. If the expression is correct, select OK.

  11. Select the Test button from the View Designer toolbar to see your view in Run mode.

Example

if you wanted to add a column that contains the total price for an order, you would create an expression that combines the values of two other columns in your table. The expression would look something like this: 

  sum(orderdetails.unitprice * orderdetails.quantity)

Creating full text search views

You can create a full-text search queries for bands within a view.

    For more information, see the section on creating full text search views in the Full Text Search chapter of the online Tools Guide.




Copyright © 2000, SilverStream Software, Inc. All rights reserved.