Skip to content

Web Application Structure and Classes

Font Icon CSS Class Styles
Creating and Maintaining a Web Application

The Web Framework classes primarily consist of containers and controls.

Containers

The main application container class is based on cWebApp. There will be one and only one cWebApp object per web application. All other web objects must be created within this singleton object.

The cWebApp object will contain views (cWebView) and modal dialogs (cWebModalDialog). It will also contain the menu and toolbar system (cWebCommandBar).

A view or a dialog container will contain a DDO structure and web panels (cWebPanel). The web panels will contain either web controls or nested web panels.

Web Panels

A web panel is used to determine the general layout of a view or modal dialog. They are placed inside of a view, dialog, or any other web panel. Up to five panels may be created at any level, each in its own region – top, bottom, left, right, and center. A cWebPanel’s region is determined by the peRegion property. Either zero or one object instance of each region is allowed.

All regions are sized automatically (based on the contents of the panel) or explicitly using the piHeight and piWidth properties. The center region (prCenter), which is the default, is special. When a browser is resized, this region resizes to fill the space (assuming you have not set piHeight and piWidth). It is common to only set the piWidth of panels set to the left or right region and the piHeight of panels set to the top or bottom region.

The piMinHeight and piMinWidth properties can be used to set a minimum view or panel size.

Height and width metrics are measured in pixels (actually browser logical pixels). The exception to this is web grid columns, which are measured as a ratio of all columns.

A web panel may contain nested web panels or nested web controls but not both. Typically, a web panel contains controls. When used in such a manner, the web panel is divided into equally sized columns, which is determined by the piColumnCount property. Web controls are then placed within these columns. You determine the horizontal location of a web control using piColumnIndex and the width of a column using piColumnSpan. The greater the number of columns in a panel, the greater the granularity allowed for control location and sizing. We have found that using a piColumnCount of 6 to 10 provides satisfactory granularity.

The cWebView and cWebModalDialog classes are themselves panels. Therefore, the simplest view structure would be the following:

oWebView
    DDO Object Structure
    oWebObject_1
    oWebObject_2
    oWebObject_n

If you decided you wanted to create additional panels, for example, a button bar at the bottom of your view, you would need to create a child center panel, move the controls into that panel, create a child bottom panel, and move the buttons into that panel.

oWebView
    DDO Object Structure
    oCenterWebPanel
        oWebObject_1
        oWebObject_2
        oWebObject_n
    oBottomWebPanel
        oWebButton_1
        oWebButton_n

We have found a good starting point is to always create a center web panel within your view. This makes it easy to add additional panels without restructuring your objects. This is the model that the wizards follow.

oWebView
    DDO Object Structure
    oCenterWebPanel
        oWebObject_1
        oWebObject_2
        oWebObject_n

Tab Dialogs

Tab dialogs are an exception. A tab dialog consists of a cWebTabContainer object, which contains one or more cWebTabPage objects. Only tab page web objects are allowed inside a tab dialog. The cWebTabContainer is actually a control but it has a mix of control and container behaviors. Its horizontal location and sizing is determined by piColumnIndex and piColumnSpan. Its default behavior is to start at column 0 and span all columns. The height of a tab dialog is determined automatically by the size of nested controls or manually by setting piHeight. The piMinHeight is also supported. Alternatively, you can also set pbFillHeight to instruct the tab dialog to fill to the remaining height.

The cWebTabPage is a container, which is always sized to fill the size of the container tab dialog. The tab page objects support piColumnCount.

Cards

Card containers provide a container that allows card panels to be stacked on top of each other. Card panels in turn will contain controls that belong to that card. Only one card is displayed at a time and an interface exists for navigating through the stack of cards.

Card containers are ideal for building wizard dialogs, for overlaying groups of controls in your view, or any use you can imagine where control paging is required. You can think of card containers as a general-purpose version of a tab dialog, or a tab dialog as a specialized version of a card container which, in fact, it is!

Use the cWebCardContainer class to create a container object for a set of cWebCard objects. Each cWebCard will contain the web control objects that you require.

Groups

The cWebGroup can be positioned as a control but is used as a container to manage both the visual interface and application flow. It has a caption and border.

Summary

The important panel properties that determine the behavior of web panels are peRegion, piColumnCount, piWidth, piHeight, piMinWidth, and piMinHeight.

Web controls must be placed inside of a web panel. We currently support the following controls:

Web controls must be placed within a web container:

Web objects may not be nested inside of a web control (the exception being grids which may contain web column objects). A web control may reside with other web control sibling objects. You may not mix web panels and web controls as siblings.

Web Control Names

Web objects on the server and client are synchronized by their names. Therefore, each web object must be uniquely named. The complete name must be unique, which means that no two web siblings can have the same name. If two objects do share the same name, an error will be reported in the WebApp Designer and at runtime. An error is not reported at compile time.

Web Control Size and Location

A web control’s X coordinate placement and width is determined by its piColumnIndex and piColumnSpan properties and its parent’s piColumnCount property. The parent piColumnCount property determines how many equally spaced columns are created. The piColumnIndex determines which column the control starts and piColumnSpan determines how many columns the control will span. The default piColumnIndex is 0, which means that each control is located on its own line and the default piColumnSpan is 1, which means it will span one column. The actual width is determined by the number of columns and the width of the panel. Indexes and spans that are out of range will adjust the best they can by trying to fit within the panel.

The pbFillHeight property instructs a control to fill the remaining height of its panel. This is often used with grids and multi-line edits.

Control Labels

Controls support labels, which normally appear to the left of the control. The pbShowLabel determines if a control should display a label. The psLabel controls the content of the label. When a label is shown, the column width is split between the label and the control. By default, the first 120 pixels will be used by the label, while the remaining width will be used to render the control. This all occurs within the first column – if the control spans additional columns, the control will be resized to fill those additional columns.

The width of a label can be set using piLabelOffset; the smaller the offset, the more space for the control. If you change the label offset for a control, you will often want to change this for all controls within the column so your controls align properly to the left.

A label’s position relative to the control (left, right, top, bottom) is set by peLabelPosition. A label’s alignment (left, right, center) is set by peLabelAlign.

Grids

Grids are special in that they are web controls that support the nesting of web column controls. The size and location of a grid is determined by its properties (piColumnIndex, piColumnSpan, piHeight, piWidth, piMinHeight, piMinWidth, pbFillHeight) while a column’s behaviors are determined by the type of column object (form, checkbox, combo) and its properties (piWidth, psCaption). While almost all of the other width measurements are logical pixels, the width of a grid is determined as a ratio of the sum of all column widths.

DEO versus non-DEO controls

In the Windows framework, there is a separate class lineage for data-aware and non-data-aware containers and controls. For example, there is a view and a dbView, or a Form and a dbForm. This distinction is not made with the WebApp classes and any control (or container) can be used as a DEO or non-DEO object. If the control is bound to a DD field using the Entry_Item command, it will be used as a DEO control. If it is not, it is a simple control.

The controls typically used for data binding are cWebForm, cWebCombo, cWebCheckbox, cWebEdit, cWebGrid, cWebPromptList, cWebColumn, cWebColumnCombo, and cWebColumnCheckBox.

The other controls are usually managed manually.

Previous Topic: Font Icon CSS Class Styles
Next Topic: Creating and Maintaining a Web Application

See Also

Developing Web Applications