Working with Windows and Tabs

Overview

• What you’ll learn: The window and tab structure that forms iDempiere’s user interface, including the header/line pattern, parent-child tab relationships, tab levels, display logic, field groups, and navigation strategies for complex windows.
• Prerequisites: Lesson 5 – Understanding the Application Dictionary
• Estimated reading time: 22 minutes

Introduction

In the previous lesson, you learned that iDempiere’s Application Dictionary defines every aspect of the user interface through metadata. Now it is time to explore how that metadata comes together in practice. Windows and tabs are the primary mechanisms through which users interact with data in iDempiere. A well-designed window organizes related data into a logical hierarchy of tabs, making it possible to view and edit complex business entities without navigating away to separate screens.

This lesson covers the structural patterns, configuration options, and navigation techniques that every iDempiere user and administrator should master. By the end, you will be able to read and understand any window’s tab structure, recognize the header/line pattern used throughout the system, and configure field-level display behavior.

The Header/Line Pattern

The most pervasive structural pattern in iDempiere is the header/line pattern (also called the master/detail pattern). This pattern separates a business document into two parts:

• The header contains information that applies to the entire document: the business partner, the date, the warehouse, the document number, and overall status.
• The lines contain the individual items or entries that make up the document: each product, quantity, price, and line-level detail.

This pattern maps directly to the relational database model. The header is stored in one table, and the lines are stored in a related table with a foreign key back to the header.

Examples Throughout the System

Understanding this pattern is essential because virtually every transactional window in iDempiere follows it. When you open the Sales Order window, the first tab displays the order header, and the second tab displays the order lines. Selecting a specific order on the header tab automatically filters the line tab to show only lines belonging to that order.

Parent-Child Tab Relationships

The header/line pattern is a specific case of a more general concept: parent-child tab relationships. In the Application Dictionary, these relationships are established through three mechanisms working together.

Tab Levels

Every tab has a TabLevel that defines its position in the hierarchy:

• Level 0: The header or main record. There is typically one level-0 tab per window, and it appears first.
• Level 1: Detail records that belong to a level-0 record. These are the most common child tabs.
• Level 2: Sub-detail records that belong to a level-1 record. Used when the detail itself has children.
• Level 3 and beyond: Deeper hierarchies, though these are rare in practice.

When a user selects a record on a level-0 tab, all level-1 tabs automatically filter their content to show only records related to the selected parent. The same cascading behavior applies at every level: selecting a level-1 record filters level-2 tabs, and so on.

Link Columns

The filtering between parent and child tabs relies on link columns. A link column is the foreign key that connects the child table to the parent table. In many cases, iDempiere can determine the link column automatically by matching the parent table’s primary key column name. For example, if the parent tab uses the C_Order table, iDempiere looks for a column named C_Order_ID in the child tab’s table.

When the automatic detection does not apply (for example, when a child table has multiple foreign keys to different parent tables), you must explicitly set the AD_Column_ID (Parent Link Column) on the child tab’s AD_Tab record.

Sequence Numbers

The SeqNo field on each tab determines the order in which tabs appear within the window. Tabs are rendered left to right (or top to bottom in the tab list) in ascending sequence order. It is conventional to use increments of 10 (10, 20, 30, …) to allow room for inserting new tabs later.

The combination of tab level and sequence number produces the visual hierarchy. Consider this example layout:

SeqNo 10, Level 0: Order Header
SeqNo 20, Level 1: Order Line
SeqNo 30, Level 2: Line Tax
SeqNo 40, Level 1: Order Tax (Summary)
SeqNo 50, Level 1: Payment Schedule

In this arrangement, the “Line Tax” tab (level 2) is a child of “Order Line” (level 1), while “Order Tax” and “Payment Schedule” are siblings of “Order Line,” all children of “Order Header.”

Single-Record vs Multi-Row Display

Each tab can be configured to display data in two modes:

• Single-record (form view): Displays one record at a time with labeled fields arranged in a form layout. This is the default for header tabs and is best suited for records with many fields.
• Multi-row (grid view): Displays multiple records in a tabular grid. This is common for line-level tabs where users need to see many records simultaneously.

The IsSingleRow attribute on the AD_Tab record sets the default display mode, but users can always toggle between form and grid view using the toolbar buttons. In the ZK web client, the toggle icon switches between these views instantly.

Tip: Line-level tabs are typically configured with IsSingleRow = N so they default to grid view, allowing users to quickly scan all line items. Header tabs use IsSingleRow = Y for the form layout that better accommodates their numerous fields.

Sort Order and Filtering

Tabs control data presentation through several ordering and filtering mechanisms:

OrderByClause

The OrderByClause on AD_Tab defines the default SQL ORDER BY for records displayed in the tab. For example, an order line tab might use Line to sort by line number. If no OrderByClause is specified, records are sorted by the primary key.

WhereClause

The WhereClause on AD_Tab adds a permanent SQL WHERE filter. This is used when the same database table is displayed by multiple tabs but each tab should show a different subset. For instance, a window might have separate tabs for active and inactive records, both pointing to the same table but with different WHERE clauses (IsActive='Y' and IsActive='N').

Field-Level Sort

Individual fields can specify a SortNo in AD_Field. Fields with non-zero SortNo values contribute to the grid view’s default column sorting.

Display Logic and Read-Only Logic

One of the most powerful features of the Application Dictionary is the ability to control visibility and editability dynamically using logic expressions. These expressions reference context variables and evaluate to true or false at runtime.

Display Logic on Fields

The DisplayLogic attribute on AD_Field controls whether a field is visible. The expression uses context variables (prefixed with @) and simple comparison operators. Examples:

@IsSOTrx@='Y'
  -- Show this field only for sales transactions

@DocStatus@='DR' | @DocStatus@='IP'
  -- Show only when document is Draft or In Progress

@PaymentRule@='S' | @PaymentRule@='B'
  -- Show only for Check or Direct Deposit payments

The syntax supports:

• = (equals)
• ! (not equals, as @Field@!'Y')
• & (logical AND)
• | (logical OR)
• ^ (comparison with context variables: @Value@^@OtherValue@)

Display Logic on Tabs

Tabs themselves can also have DisplayLogic expressions. When a tab’s display logic evaluates to false, the entire tab is hidden. This is useful for showing customer-specific tabs only when the business partner is flagged as a customer, for example.

Read-Only Logic

The ReadOnlyLogic attribute on both AD_Tab and AD_Field controls editability. When the expression evaluates to true, the tab or field becomes read-only. A common use case is making a document tab read-only once it has been completed:

@Processed@='Y' | @DocStatus@='CO'
  -- Read-only when processed or completed

Mandatory Logic

While the IsMandatory flag on AD_Column is static, the MandatoryLogic attribute on AD_Column can make a field conditionally required. For example:

@PaymentRule@='T'
  -- Mandatory only when payment rule is Direct Debit

Default Values

Default values streamline data entry by pre-populating fields when a new record is created. The DefaultValue attribute on AD_Column supports several expression types:

• Literal values: Y, N, 0, or any fixed string.
• Context variables: @#Date@ (login date), @#AD_Client_ID@ (current client), @#AD_Org_ID@ (current organization).
• Parent context: @C_BPartner_ID@ to inherit the business partner from the parent tab.
• SQL expressions: @SQL=SELECT MAX(Line)+10 FROM C_OrderLine WHERE C_Order_ID=@C_Order_ID@ to auto-calculate the next line number.

Default values are evaluated at the moment a new record is initiated. They can reference any context variable that is available at that point, including values from parent tabs.

Field Groups and Collapsing

When a tab contains many fields, the form view can become long and difficult to navigate. Field groups (defined in AD_FieldGroup and referenced by AD_Field) organize related fields under collapsible headers. For example, the Business Partner window groups fields into sections like “Address,” “Contact,” “Credit,” and “Accounting.”

Field groups can be configured with a FieldGroupType:

• Label: A simple text separator that visually divides the form.
• Collapsible: A section that can be expanded or collapsed by the user. This is the most common type.
• Tab: Renders the group as a sub-tab within the form view (used in some UI implementations).

Navigating Complex Multi-Tab Windows

Some windows in iDempiere have many tabs organized in deep hierarchies. The Business Partner window, for example, can have over ten tabs across multiple levels. Efficient navigation requires understanding a few key techniques.

The Tab Hierarchy Indicator

In the ZK web client, tabs at level 1 and deeper are indented or visually distinguished from the level-0 tab. This indentation provides a quick visual cue about the parent-child structure.

Record Navigation and Context

When you select a record on a parent tab and then switch to a child tab, the child tab automatically shows only the related records. The status bar at the bottom of the window typically shows the current record count (e.g., “Record 1/5”), confirming how many child records exist for the selected parent.

Breadcrumb Context

The window title and breadcrumb area often display identifying information from the parent record, helping you stay oriented. For example, when viewing order lines, the header information (document number, business partner) remains visible.

Example: Exploring the Business Partner Window

The Business Partner window is one of the most complex and frequently used windows in iDempiere. Let us examine its tab structure as a practical example.

Header Tab (Level 0): Business Partner

The main tab contains the core business partner information:

• Search Key (Value): A unique identifier for the BP, often auto-generated.
• Name / Name 2: The business partner’s display name.
• BP Group: A classification category (e.g., Standard, VIP, Government).
• Customer / Vendor / Employee flags: Check boxes that determine which roles this BP plays.
• Tax ID, DUNS, NAICS: Identification numbers.
• Credit fields: Credit limit, open balance, credit status.

Customer Tab (Level 1)

Visible only when the Customer flag is checked (via display logic @IsCustomer@='Y'), this tab contains customer-specific settings: payment rule, payment term, price list, discount schema, and sales representative assignment.

Vendor Tab (Level 1)

Similarly gated by @IsVendor@='Y', this tab holds vendor-specific settings: purchase payment term, PO price list, and vendor category.

Location Tab (Level 1)

Manages the BP’s physical addresses through the C_BPartner_Location table. Each BP can have multiple locations (bill-to, ship-to, remit-to, pay-from). The location data itself is stored in C_Location, which the C_BPartner_Location record references.

Contact Tab (Level 1)

Stores contact persons via the AD_User table linked to the BP by C_BPartner_ID. Each contact has a name, email, phone, and optional login credentials. Multiple contacts can exist per business partner.

Bank Account Tab (Level 1)

Manages the BP’s bank accounts for payment processing. Links to the C_BP_BankAccount table and stores bank name, routing number, account number, and other banking details.

This window perfectly illustrates how the Application Dictionary’s tab system organizes complex, multi-faceted business data into a navigable hierarchy. Each tab serves a distinct purpose, and the parent-child relationships ensure that users always see contextually relevant data.

Key Takeaways

• The header/line pattern is the fundamental structural pattern in iDempiere, separating document-wide information from individual line items.
• Tab levels (0, 1, 2, …) create parent-child hierarchies where selecting a parent record automatically filters child tabs.
• Link columns connect child tabs to their parent, either automatically (by matching the parent’s primary key column name) or explicitly (via the AD_Tab parent link column setting).
• Display logic, read-only logic, and mandatory logic use context variable expressions to dynamically control field and tab behavior.
• Default values support literals, context variables, parent context, and SQL expressions to streamline data entry.
• Field groups organize large forms into collapsible sections for easier navigation.
• Complex windows like Business Partner demonstrate how multiple levels of tabs manage rich, interconnected data.

What’s Next

In the next lesson, Data Model Fundamentals, you will explore the core database tables and naming conventions that underpin every iDempiere system. You will learn about the standard column patterns, table prefixes, the client-organization data isolation model, and the key entities that drive all business processes.

SeqNo 10, Level 0: Order Header
SeqNo 20, Level 1: Order Line
SeqNo 30, Level 2: Line Tax
SeqNo 40, Level 1: Order Tax (Summary)
SeqNo 50, Level 1: Payment Schedule

@IsSOTrx@='Y'
  -- 僅在銷售交易時顯示此欄位

@DocStatus@='DR' | @DocStatus@='IP'
  -- 僅在文件為草稿或處理中時顯示

@PaymentRule@='S' | @PaymentRule@='B'
  -- 僅在支票或直接存款付款時顯示

@Processed@='Y' | @DocStatus@='CO'
  -- 處理完成或已完成時唯讀

SeqNo 10, Level 0: Order Header
SeqNo 20, Level 1: Order Line
SeqNo 30, Level 2: Line Tax
SeqNo 40, Level 1: Order Tax (Summary)
SeqNo 50, Level 1: Payment Schedule

@IsSOTrx@='Y'
  -- 販売取引の場合にのみ表示

@DocStatus@='DR' | @DocStatus@='IP'
  -- 下書きまたは処理中の場合にのみ表示

@PaymentRule@='S' | @PaymentRule@='B'
  -- 小切手またはダイレクトデポジットの場合にのみ表示

@Processed@='Y' | @DocStatus@='CO'
  -- 処理済みまたは完了時に読み取り専用