546 lines
16 KiB
Markdown
546 lines
16 KiB
Markdown
# SAPUI5 Core Architecture & Concepts
|
|
|
|
**Source**: Official SAP SAPUI5 Documentation
|
|
**Documentation**: [https://github.com/SAP-docs/sapui5/tree/main/docs/04_Essentials](https://github.com/SAP-docs/sapui5/tree/main/docs/04_Essentials)
|
|
**Last Updated**: 2025-11-21
|
|
|
|
---
|
|
|
|
## Framework Architecture
|
|
|
|
### Component-Based Architecture
|
|
|
|
SAPUI5 applications are built around **Components** - self-contained, reusable units with:
|
|
- **manifest.json**: Application descriptor with metadata and configuration
|
|
- **Component.js**: Component controller with initialization logic
|
|
- **View/Controller pairs**: UI definition and business logic
|
|
- **i18n**: Internationalization resources
|
|
- **model**: Optional local data models
|
|
|
|
**Key Benefits**:
|
|
- Reusability across applications
|
|
- Clear separation of concerns
|
|
- Standardized configuration via manifest
|
|
- Dependency management
|
|
- Lifecycle management
|
|
|
|
**Documentation**: [https://github.com/SAP-docs/sapui5/tree/main/docs/04_Essentials](https://github.com/SAP-docs/sapui5/tree/main/docs/04_Essentials) (search: component)
|
|
|
|
---
|
|
|
|
### Model-View-Controller (MVC) Pattern
|
|
|
|
SAPUI5 implements MVC for clean separation:
|
|
|
|
**Model** (Data Layer):
|
|
- Provides data to UI
|
|
- Notifies views of changes
|
|
- Types: JSON, OData v2/v4, XML, Resource
|
|
- Supports binding for automatic UI updates
|
|
|
|
**View** (Presentation Layer):
|
|
- Defines UI structure
|
|
- Available types: XML (recommended), JSON, JavaScript, HTML
|
|
- Contains controls and layout
|
|
- No business logic
|
|
|
|
**Controller** (Logic Layer):
|
|
- Event handlers for user interactions
|
|
- Business logic
|
|
- Data formatting
|
|
- Navigation
|
|
- Lifecycle hooks: onInit, onBeforeRendering, onAfterRendering, onExit
|
|
|
|
**Documentation**: [https://github.com/SAP-docs/sapui5/tree/main/docs/04_Essentials](https://github.com/SAP-docs/sapui5/tree/main/docs/04_Essentials) (search: mvc, controller, view)
|
|
|
|
---
|
|
|
|
### Module System
|
|
|
|
SAPUI5 uses AMD (Asynchronous Module Definition):
|
|
|
|
**Module Definition**:
|
|
```javascript
|
|
sap.ui.define([
|
|
"sap/ui/core/mvc/Controller",
|
|
"sap/m/MessageToast"
|
|
], function(Controller, MessageToast) {
|
|
"use strict";
|
|
|
|
return Controller.extend("my.namespace.controller.Main", {
|
|
onPress: function() {
|
|
MessageToast.show("Button pressed");
|
|
}
|
|
});
|
|
});
|
|
```
|
|
|
|
**Module Loading**:
|
|
```javascript
|
|
sap.ui.require([
|
|
"sap/m/MessageBox"
|
|
], function(MessageBox) {
|
|
MessageBox.success("Loaded asynchronously");
|
|
});
|
|
```
|
|
|
|
**Key Points**:
|
|
- **sap.ui.define**: For defining modules (always use this)
|
|
- **sap.ui.require**: For loading modules dynamically
|
|
- Async loading prevents blocking
|
|
- Dependencies declared explicitly
|
|
- Supports lazy loading
|
|
|
|
**Documentation**: [https://github.com/SAP-docs/sapui5/tree/main/docs/04_Essentials](https://github.com/SAP-docs/sapui5/tree/main/docs/04_Essentials) (search: module, define, require)
|
|
|
|
---
|
|
|
|
### Bootstrapping
|
|
|
|
Initialize SAPUI5 in index.html:
|
|
|
|
**Basic Bootstrap**:
|
|
```html
|
|
<script
|
|
id="sap-ui-bootstrap"
|
|
src="resources/sap-ui-core.js"
|
|
data-sap-ui-theme="sap_horizon"
|
|
data-sap-ui-libs="sap.m"
|
|
data-sap-ui-resourceroots='{
|
|
"my.namespace": "./"
|
|
}'
|
|
data-sap-ui-async="true"
|
|
data-sap-ui-onInit="module:my/namespace/index"
|
|
data-sap-ui-compatVersion="edge">
|
|
</script>
|
|
```
|
|
|
|
**Key Configuration Options**:
|
|
- `data-sap-ui-theme`: UI theme (sap_horizon, sap_fiori_3, etc.)
|
|
- `data-sap-ui-libs`: Preloaded libraries
|
|
- `data-sap-ui-resourceroots`: Namespace-to-path mapping
|
|
- `data-sap-ui-async="true"`: Async loading (always use)
|
|
- `data-sap-ui-compatVersion="edge"`: Latest features
|
|
- `data-sap-ui-onInit`: Module to run after initialization
|
|
|
|
**CDN Options**:
|
|
- SAP CDN: `[https://sapui5.hana.ondemand.com/resources/sap-ui-core.js`](https://sapui5.hana.ondemand.com/resources/sap-ui-core.js`)
|
|
- OpenUI5 CDN: `[https://openui5.hana.ondemand.com/resources/sap-ui-core.js`](https://openui5.hana.ondemand.com/resources/sap-ui-core.js`)
|
|
- Specific version: `[https://sapui5.hana.ondemand.com/1.120.0/resources/sap-ui-core.js`](https://sapui5.hana.ondemand.com/1.120.0/resources/sap-ui-core.js`)
|
|
|
|
**Documentation**: [https://github.com/SAP-docs/sapui5/tree/main/docs/04_Essentials](https://github.com/SAP-docs/sapui5/tree/main/docs/04_Essentials) (search: bootstrap, initialization)
|
|
|
|
---
|
|
|
|
### Libraries
|
|
|
|
SAPUI5 provides multiple control libraries:
|
|
|
|
**Main Libraries**:
|
|
- **sap.m**: Mobile/responsive controls (Button, Table, List, etc.)
|
|
- **sap.ui.core**: Core framework (mvc, routing, etc.)
|
|
- **sap.ui.table**: High-performance tables
|
|
- **sap.f**: SAP Fiori controls (FlexibleColumnLayout, etc.)
|
|
- **sap.uxap**: UX Add-on (ObjectPageLayout, etc.)
|
|
- **sap.ui.layout**: Layout controls (Grid, Splitter, etc.)
|
|
- **sap.tnt**: Tool Navigation Template (SideNavigation, etc.)
|
|
- **sap.suite.ui.commons**: Suite controls (charts, micro-charts)
|
|
|
|
**Library Loading**:
|
|
```javascript
|
|
// In manifest.json
|
|
{
|
|
"sap.ui5": {
|
|
"dependencies": {
|
|
"libs": {
|
|
"sap.m": {},
|
|
"sap.ui.table": {},
|
|
"sap.f": {}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Lazy Loading**:
|
|
```javascript
|
|
sap.ui.getCore().loadLibrary("sap.ui.table", { async: true })
|
|
.then(function() {
|
|
// Library loaded
|
|
});
|
|
```
|
|
|
|
**Documentation**: [https://github.com/SAP-docs/sapui5/tree/main/docs/02_Read-Me-First](https://github.com/SAP-docs/sapui5/tree/main/docs/02_Read-Me-First) (search: library, supported-library-combinations)
|
|
|
|
---
|
|
|
|
### Namespacing
|
|
|
|
Proper namespacing prevents conflicts:
|
|
|
|
**Structure**:
|
|
```
|
|
com.mycompany.myapp/
|
|
├── Component.js
|
|
├── manifest.json
|
|
├── controller/
|
|
│ └── Main.controller.js
|
|
├── view/
|
|
│ └── Main.view.xml
|
|
├── model/
|
|
│ └── formatter.js
|
|
└── i18n/
|
|
└── i18n.properties
|
|
```
|
|
|
|
**Naming Conventions**:
|
|
- Reverse domain: `com.mycompany.myapp`
|
|
- PascalCase for classes: `Main.controller.js`
|
|
- camelCase for files: `formatter.js`
|
|
- Folder names: lowercase (controller, view, model)
|
|
|
|
**Resource Root Registration**:
|
|
```javascript
|
|
// In index.html
|
|
data-sap-ui-resourceroots='{
|
|
"com.mycompany.myapp": "./"
|
|
}'
|
|
```
|
|
|
|
**Documentation**: [https://github.com/SAP-docs/sapui5/tree/main/docs/05_Developing_Apps](https://github.com/SAP-docs/sapui5/tree/main/docs/05_Developing_Apps) (search: folder-structure, namespace)
|
|
|
|
---
|
|
|
|
### Control Tree & Rendering
|
|
|
|
SAPUI5 builds a tree of controls:
|
|
|
|
**Control Hierarchy**:
|
|
- **Root Element**: `<body>` or specific `<div>`
|
|
- **Component Container**: Hosts component
|
|
- **View**: Contains controls
|
|
- **Controls**: UI elements (Button, Input, Table, etc.)
|
|
- **Aggregations**: Child controls (items, content, etc.)
|
|
|
|
**Rendering Process**:
|
|
1. **Initial Rendering**: Creates HTML from control tree
|
|
2. **Re-rendering**: Updates DOM when model/property changes
|
|
3. **Invalidation**: Marks controls for re-rendering
|
|
4. **Batching**: Groups re-renders for performance
|
|
|
|
**Lifecycle Hooks**:
|
|
- `onBeforeRendering()`: Before DOM update
|
|
- `onAfterRendering()`: After DOM update (DOM manipulation here)
|
|
|
|
**Documentation**: [https://github.com/SAP-docs/sapui5/tree/main/docs/04_Essentials](https://github.com/SAP-docs/sapui5/tree/main/docs/04_Essentials) (search: rendering, control-tree)
|
|
|
|
---
|
|
|
|
### Fragments
|
|
|
|
Reusable UI snippets without controller:
|
|
|
|
**XML Fragment** (recommended):
|
|
```xml
|
|
<core:FragmentDefinition
|
|
xmlns="sap.m"
|
|
xmlns:core="sap.ui.core">
|
|
<Dialog
|
|
title="{i18n>dialogTitle}"
|
|
type="Message">
|
|
<Text text="{i18n>dialogText}"/>
|
|
<buttons>
|
|
<Button text="{i18n>close}" press=".onCloseDialog"/>
|
|
</buttons>
|
|
</Dialog>
|
|
</core:FragmentDefinition>
|
|
```
|
|
|
|
**Loading Fragments**:
|
|
```javascript
|
|
// In controller
|
|
onOpenDialog: function() {
|
|
if (!this.pDialog) {
|
|
this.pDialog = this.loadFragment({
|
|
name: "my.namespace.view.fragments.MyDialog"
|
|
});
|
|
}
|
|
this.pDialog.then(function(oDialog) {
|
|
oDialog.open();
|
|
});
|
|
}
|
|
```
|
|
|
|
**Benefits**:
|
|
- Reuse across views
|
|
- Smaller view files
|
|
- Modular UI definition
|
|
- No separate controller
|
|
|
|
**Documentation**: [https://github.com/SAP-docs/sapui5/tree/main/docs/04_Essentials](https://github.com/SAP-docs/sapui5/tree/main/docs/04_Essentials) (search: fragment)
|
|
|
|
---
|
|
|
|
### Application Descriptor (manifest.json)
|
|
|
|
Central configuration file:
|
|
|
|
**Structure**:
|
|
```json
|
|
{
|
|
"sap.app": {
|
|
"id": "com.mycompany.myapp",
|
|
"type": "application",
|
|
"title": "{{appTitle}}",
|
|
"description": "{{appDescription}}",
|
|
"applicationVersion": {
|
|
"version": "1.0.0"
|
|
},
|
|
"dataSources": {
|
|
"mainService": {
|
|
"uri": "/sap/opu/odata/sap/SERVICE_SRV/",
|
|
"type": "OData",
|
|
"settings": {
|
|
"odataVersion": "2.0"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"sap.ui": {
|
|
"technology": "UI5",
|
|
"deviceTypes": {
|
|
"desktop": true,
|
|
"tablet": true,
|
|
"phone": true
|
|
}
|
|
},
|
|
"sap.ui5": {
|
|
"rootView": {
|
|
"viewName": "com.mycompany.myapp.view.App",
|
|
"type": "XML",
|
|
"async": true,
|
|
"id": "app"
|
|
},
|
|
"dependencies": {
|
|
"minUI5Version": "1.120.0",
|
|
"libs": {
|
|
"sap.m": {},
|
|
"sap.ui.core": {}
|
|
}
|
|
},
|
|
"models": {
|
|
"i18n": {
|
|
"type": "sap.ui.model.resource.ResourceModel",
|
|
"settings": {
|
|
"bundleName": "com.mycompany.myapp.i18n.i18n"
|
|
}
|
|
},
|
|
"": {
|
|
"dataSource": "mainService",
|
|
"settings": {
|
|
"defaultBindingMode": "TwoWay"
|
|
}
|
|
}
|
|
},
|
|
"routing": {
|
|
"config": {
|
|
"routerClass": "sap.m.routing.Router",
|
|
"type": "View",
|
|
"viewType": "XML",
|
|
"path": "com.mycompany.myapp.view",
|
|
"controlId": "app",
|
|
"controlAggregation": "pages",
|
|
"async": true
|
|
},
|
|
"routes": [],
|
|
"targets": {}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Key Sections**:
|
|
- **sap.app**: General app info and data sources
|
|
- **sap.ui**: UI technology and device types
|
|
- **sap.ui5**: UI5-specific config (models, routing, dependencies)
|
|
|
|
**Documentation**: [https://github.com/SAP-docs/sapui5/tree/main/docs/04_Essentials](https://github.com/SAP-docs/sapui5/tree/main/docs/04_Essentials) (search: manifest, descriptor)
|
|
|
|
---
|
|
|
|
## Core Concepts
|
|
|
|
### Properties, Events, Aggregations
|
|
|
|
**Properties**:
|
|
- Simple values (text, enabled, visible)
|
|
- Accessed via getters/setters
|
|
- Support data binding
|
|
- Example: `oButton.setText("Click me")`
|
|
|
|
**Events**:
|
|
- User interactions or state changes
|
|
- Attach handlers with `.attachEvent()` or in XML
|
|
- Event object contains source and parameters
|
|
- Example: `press`, `change`, `selectionChange`
|
|
|
|
**Aggregations**:
|
|
- Child controls (items, content, buttons)
|
|
- One-to-many relationships
|
|
- Managed by parent control
|
|
- Example: Table has `items`, Page has `content`
|
|
|
|
**Associations**:
|
|
- References to other controls
|
|
- Not parent-child relationship
|
|
- Example: Label's `labelFor` association
|
|
|
|
**Documentation**: [https://github.com/SAP-docs/sapui5/tree/main/docs/04_Essentials](https://github.com/SAP-docs/sapui5/tree/main/docs/04_Essentials) (search: property, event, aggregation)
|
|
|
|
---
|
|
|
|
### Device Adaptation
|
|
|
|
Responsive design features:
|
|
|
|
**Content Density**:
|
|
- **Cozy**: Touch-friendly (larger targets) - default on phones
|
|
- **Compact**: Mouse-friendly (smaller) - default on desktops
|
|
- Set via CSS class: `sapUiSizeCozy` or `sapUiSizeCompact`
|
|
|
|
**Device Detection**:
|
|
```javascript
|
|
sap.ui.Device.system.phone
|
|
sap.ui.Device.system.tablet
|
|
sap.ui.Device.system.desktop
|
|
```
|
|
|
|
**Responsive Controls**:
|
|
- Use `sap.m` controls (designed for responsive)
|
|
- FlexBox for flexible layouts
|
|
- Grid for responsive grids
|
|
- Avoid fixed pixel sizes
|
|
|
|
**Documentation**: [https://github.com/SAP-docs/sapui5/tree/main/docs/04_Essentials](https://github.com/SAP-docs/sapui5/tree/main/docs/04_Essentials) (search: device, responsive, content-density)
|
|
|
|
---
|
|
|
|
### Theming
|
|
|
|
Visual design system:
|
|
|
|
**Available Themes**:
|
|
- **sap_horizon**: Latest SAP theme (recommended)
|
|
- **sap_fiori_3**: SAP Fiori 3.0 theme
|
|
- **sap_fiori_3_dark**: Dark variant
|
|
- **sap_fiori_3_hcb**: High contrast black
|
|
- **sap_fiori_3_hcw**: High contrast white
|
|
|
|
**Setting Theme**:
|
|
```html
|
|
<!-- In index.html -->
|
|
data-sap-ui-theme="sap_horizon"
|
|
```
|
|
|
|
```javascript
|
|
// Dynamically
|
|
sap.ui.getCore().applyTheme("sap_horizon");
|
|
```
|
|
|
|
**Theme Parameters**:
|
|
- Use in custom CSS for consistency
|
|
- Example: `@sapUiBaseColor`, `@sapUiBaseBG`
|
|
- Access via: `Parameters.get("sapUiBaseColor")`
|
|
|
|
**Custom Themes**:
|
|
- Use UI Theme Designer
|
|
- Based on SAP theme
|
|
- Only override needed parameters
|
|
|
|
**Documentation**: [https://github.com/SAP-docs/sapui5/tree/main/docs/02_Read-Me-First](https://github.com/SAP-docs/sapui5/tree/main/docs/02_Read-Me-First) (search: theme, supported-combinations)
|
|
|
|
---
|
|
|
|
## Performance Optimization
|
|
|
|
**Best Practices**:
|
|
|
|
1. **Async Loading**:
|
|
- Always use `data-sap-ui-async="true"`
|
|
- Use `sap.ui.define` for modules
|
|
- Lazy load libraries when needed
|
|
|
|
2. **Component Preload**:
|
|
- Build creates Component-preload.js
|
|
- Bundles all component resources
|
|
- Reduces HTTP requests
|
|
|
|
3. **Data Binding**:
|
|
- Use one-way binding when possible
|
|
- Avoid complex formatters in loops
|
|
- Use `bindingMode: "OneTime"` for static data
|
|
|
|
4. **List/Table Optimization**:
|
|
- Use growing lists for large datasets
|
|
- Enable table virtualization
|
|
- Use OData paging ($skip, $top)
|
|
|
|
5. **Model Management**:
|
|
- Use batch requests for OData
|
|
- Set size limits appropriately
|
|
- Destroy models when not needed
|
|
|
|
6. **Rendering**:
|
|
- Avoid frequent re-renders
|
|
- Use `busy` state during loading
|
|
- Minimize DOM manipulations
|
|
|
|
**Documentation**: [https://github.com/SAP-docs/sapui5/tree/main/docs/05_Developing_Apps](https://github.com/SAP-docs/sapui5/tree/main/docs/05_Developing_Apps) (search: performance)
|
|
|
|
---
|
|
|
|
## Security
|
|
|
|
**Key Security Features**:
|
|
|
|
1. **XSS Prevention**:
|
|
- Automatic output encoding
|
|
- Use data binding (never innerHTML)
|
|
- Sanitize user input
|
|
|
|
2. **Content Security Policy (CSP)**:
|
|
- SAPUI5 supports CSP
|
|
- Avoid inline scripts
|
|
- Use nonce or hash for inline styles
|
|
|
|
3. **Clickjacking Prevention**:
|
|
- Frame-options header
|
|
- CSP frame-ancestors directive
|
|
|
|
4. **Input Validation**:
|
|
- Use data types
|
|
- Validate on client and server
|
|
- Use constraints (maxLength, pattern)
|
|
|
|
5. **Secure Communication**:
|
|
- Always use HTTPS in production
|
|
- Enable CORS properly
|
|
- Use CSRF tokens
|
|
|
|
**Documentation**: [https://github.com/SAP-docs/sapui5/tree/main/docs/05_Developing_Apps](https://github.com/SAP-docs/sapui5/tree/main/docs/05_Developing_Apps) (search: security, secure-programming)
|
|
|
|
---
|
|
|
|
## Links to Official Documentation
|
|
|
|
- **Core Documentation**: [https://github.com/SAP-docs/sapui5/tree/main/docs/04_Essentials](https://github.com/SAP-docs/sapui5/tree/main/docs/04_Essentials)
|
|
- **App Development**: [https://github.com/SAP-docs/sapui5/tree/main/docs/05_Developing_Apps](https://github.com/SAP-docs/sapui5/tree/main/docs/05_Developing_Apps)
|
|
- **Getting Started**: [https://github.com/SAP-docs/sapui5/tree/main/docs/03_Get-Started](https://github.com/SAP-docs/sapui5/tree/main/docs/03_Get-Started)
|
|
- **Read Me First**: [https://github.com/SAP-docs/sapui5/tree/main/docs/02_Read-Me-First](https://github.com/SAP-docs/sapui5/tree/main/docs/02_Read-Me-First)
|
|
- **API Reference**: [https://sapui5.hana.ondemand.com/#/api](https://sapui5.hana.ondemand.com/#/api)
|
|
- **Demo Kit**: [https://sapui5.hana.ondemand.com/](https://sapui5.hana.ondemand.com/)
|
|
|
|
---
|
|
|
|
**Note**: This document provides core architecture concepts for SAPUI5 development. For specific implementation details, refer to the official documentation links provided throughout this document.
|