# Popup
The **Popup** field is an input component used to display a **searchable list of records** from a database table in a **popup window**.\
It allows users to search, browse, and select a value, which is then mapped back to the main form field.
The Popup field is suitable when users need to **select a value from a large dataset** while seeing both a **code and description**.
***
### Purpose of Popup Field
The Popup field is designed to:
* Display large datasets in a dedicated popup window
* Provide a searchable selection interface
* Allow selection of reference or master data
* Map selected values back to one or more fields on the form
#### Typical Use Cases
* Customer / Vendor selection
* Product or item lookup
* Account or cost center selection
* Reference entity selection with code & description
***
#### Adding and Configuring a Popup Field
To add a Popup field:
1. Drag the **Popup** field into a Module layout
2. Click the **Edit (pencil) icon** on the field
3. The **Popup Configuration** window opens
***
### Popup Configuration Properties
#### 1️. Core Identification
| Property | Mandatory | Description |
| --------- | --------- | ---------------------------------- |
| **MF ID** | Yes | System‑generated unique identifier |
***
#### 2️. Popup Display Definition
Defines the columns shown inside the popup window.
| Property | Mandatory | Description |
| ------------------ | --------- | -------------------------------------------------- |
| **DB Column Name** | No | Database column displayed in popup |
| **Show Name** | No | Column header shown to the user |
| **Seq** | No | Display order of the column |
| **Alignment** | No | Alignment of the column |
| **Display** | Yes | Determines whether the column is visible or hidden |
***
#### 3️. Data Retrieval Logic
| Property | Mandatory | Description |
| --------------- | --------- | -------------------------------------- |
| **SQL Command** | Yes | SQL query used to retrieve popup data |
| **Search Key** | No | Column used for searching within popup |
***
#### 4️. Value Mapping Back to Form
Defines how selected values are mapped back to the main form.
| Property | Mandatory | Description |
| ---------------------- | --------- | ------------------------------------------------- |
| **Map Column** | Yes | Column whose value is saved to the main field |
| **Map Column Display** | Yes | Column displayed as code on the main field |
| **Map Description** | Yes | Column displayed as description on the main field |
***
#### 5️. Field Appearance & Behavior
| Property | Description |
| -------------------- | --------------------------------- |
| **Source Tag** | JavaScript applied at field level |
| **Text Size** | Width of the code field |
| **Max Length** | Maximum allowed characters |
| **Description Size** | Width of description field |
| **Show Go Button** | Displays a Go/Search button |
| **Map Entity** | Defines mapped entity context |
***
#### 6️. Popup Search Behavior
| Property | Description |
| ----------------------------- | ------------------------------------------------------ |
| **SearchLike in Popup** | Enables wildcard search |
| **SearchIgnoreCase in Popup** | Case‑insensitive search |
| **UNClose Flag** | Prevents popup from closing automatically on selection |
***
#### 7️. Dependency Configuration
Popup fields can depend on other field values.
| Property | Description |
| ------------------- | ------------------------------------------- |
| **Global ID** | Global identifier for dependency resolution |
| **Dependency Data** | Enables dependent behavior |
| **Depend Column** | Column dependent on another field |
| **Sequence** | Dependency evaluation order |
***
#### 8️. Database Mapping
| Property | Description |
| ------------- | ------------------------------------ |
| **Field\_ID** | Database column mapped to this field |
***
#### 9️. Display & Search Configuration (Main Screen)
| Property | Description |
| --------------------- | ------------------------------------ |
| **ShowFieldName** | Label displayed on the form |
| **SearchCriteria** | Enables field as search criteria |
| **ShowSearch** | Displays field in search results |
| **SearchFromTo** | Enables range‑based search |
| **SearchPreLike** | Enables `%XXX` wildcard search |
| **SearchLike** | Enables `XXX%` wildcard search |
| **SearchIgnoreCase** | Case‑insensitive search |
| **JoinSearchTable** | Used for JOIN‑based search |
| **SearchFieldGroup** | Horizontal position in search screen |
| **SearchCriteriaSeq** | Vertical position in search screen |
| **ShowSearchSeq** | Order in search results |
***
#### 10. UI & Behavior Flags
| Property | Description |
| --------------- | ----------------------------------------- |
| **Alignment** | Text alignment: Left / Center / Right |
| **OnlyGuiFlag** | UI‑only field (not persisted to database) |
| **ViewFlag** | Displays field in read‑only mode |
| **KeepHistory** | Persists history of value changes |
| **FilterFlag** | Filters records in 1‑Many Modules |
| **Authen** | Applies IAM‑based authorization |
| **MergeFlag** | Field spans across multiple columns |
***
#### 11. Validation Rules (Validate Code)
| Code | Description |
| -------------------- | -------------------------------- |
| `CHECK_NULL` | Prevents saving if value is null |
| `CHECK_INTEGER` | Ensures integer input |
| `CHECK_DECIMAL` | Ensures decimal input |
| `CHECK_EMAIL_FORMAT` | Validates email format |
***
### Popup vs Suggestion vs Dynamic List
| Feature | Popup | Suggestion | Dynamic List |
| ------------------- | ------------ | -------------- | --------------- |
| UI Type | Popup Window | Inline Suggest | Dropdown |
| Best for Large Data | ✅ Yes | ✅ Yes | ⚠️ Limited |
| Search UI | Dedicated | Inline typing | Dropdown filter |
| Code + Description | ✅ Yes | ✅ Yes | ⚠️ Optional |
| Complex SQL | ✅ Yes | ✅ Yes | ✅ Yes |
***
### Usage Guidelines
* Use **Popup** for large or complex datasets
* Prefer Popup when both **code and description** are required
* Ensure SQL is optimized for performance
* Enable wildcard search carefully on large tables
* Use dependencies to narrow down popup results
* Avoid overloading popup with too many columns
***
### Summary
The **Popup** field provides a powerful mechanism to **search, browse, and select data from large datasets** using a dedicated popup window.
Key points:
* Database‑driven and searchable
* Supports complex SQL queries
* Maps selected values back to the form
* Integrates with search, validation, and IAM
* Ideal for master/reference data selection
When used correctly, Popup fields deliver **high usability and accuracy** for enterprise‑grade Smart Forms in ONEWEB.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.onewebstack.com/designer-reference/app-designer/entity/create-new-entity/fields/popup.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
