diff --git a/docs/.vitepress/theme/style.css b/docs/.vitepress/theme/style.css index ba0ed38c..8844547f 100644 --- a/docs/.vitepress/theme/style.css +++ b/docs/.vitepress/theme/style.css @@ -453,26 +453,31 @@ color: var(--vp-c-brand-2); } -/* ============================================== the home page, one screen === +/* ================================================ the home page, at 90% === * - * The home page is not a page you read — it is a signpost, and a signpost you - * have to scroll is a signpost that failed. At the theme's own sizes it came - * to 1152px: hero, three cards, the samples button and the footer, on a 13" - * laptop that is a screen and a half, so the cards arrived only for readers - * who went looking for them. + * The home page is not a page you read — it is a signpost, and at the theme's + * own sizes it came to 1152px on a 1440-wide window: hero, three cards, the + * samples button and the footer, which is a screenful and a bit, so the cards + * arrived only for a reader who went looking for them. * - * Everything below is the same page at smaller numbers — nothing is dropped - * and nothing is hidden. The type stays in its ranks (the hero name is still - * the largest thing on the page, the tagline still smaller than the text it - * follows); it is the AIR that goes, which is where the theme's default is - * most generous: 144px above the hero name, 128px between the last card and - * the footer, 64px of card padding around three lines of text. + * What is below is the theme's own design at nine tenths of its numbers — + * every one of them, type included, so the page keeps its proportions + * exactly. It is the page a reader gets by pressing ctrl-minus once, written + * down: the same relationship between the hero name, the headline and the + * tagline, the same air around the cards, at a size that leaves the whole + * signpost on one screen on a large display. * - * Measured, at a 1440-wide window: 1152px -> 750px, footer included. The - * target was 800px, the working height of a 13" MacBook's browser window; - * anything taller and the footer goes under the fold again. The 50px left - * over is deliberate — it is the room a hero headline needs when it wraps to - * a second line, which it does at narrower windows and in other type. + * The first attempt at this cut harder — hero type to 40px, cards to 16px of + * padding — and hit 750px, which fit any laptop and read as a different, + * smaller page. Fitting a 13" window is not worth redesigning the front door + * for: at 90% the page is about 970px, so a 1200px-tall window shows all of + * it and a 800px one still scrolls a little. That is the deliberate trade. + * + * The one number NOT scaled is the gap under the last block: the theme's + * 128px assumes there is more page below, and here there is a footer. It is + * 48px instead. Nothing is visible in that space either way — when the page + * is shorter than the window the footer sits at the bottom regardless — so it + * costs nothing to look at and saves 80px on a short one. * * Specificity: the theme's rules are Vue SCOPED styles, so each compiles with * a `[data-v-…]` attribute — `.VPHero[data-v-x]` counts two units, and a bare @@ -489,83 +494,85 @@ * layout is one column, and a phone scrolls the home page whatever we do. */ @media (min-width: 960px) { - /* The hero. Top padding has to keep the nav-height term — the hero is - * pulled up under the fixed nav bar by a negative margin, so a plain `40px` - * would put the name behind it. */ + /* The hero: 80/64 of padding, 56/64 type, 24/36 tagline. Top padding has to + * keep the nav-height term — the hero is pulled up under the fixed nav bar + * by a negative margin, so a plain `72px` would put the name behind it. */ .Layout .VPHome .VPHero { - padding-top: calc(var(--vp-nav-height) + var(--vp-layout-top-height, 0px) + 32px); - padding-bottom: 32px; + padding-top: calc(var(--vp-nav-height) + var(--vp-layout-top-height, 0px) + 72px); + padding-bottom: 58px; } .Layout .VPHome .VPHero .name, .Layout .VPHome .VPHero .text { - font-size: 40px; - line-height: 48px; + font-size: 50px; + line-height: 58px; } .Layout .VPHome .VPHero .tagline { - padding-top: 8px; - font-size: 17px; - line-height: 26px; + padding-top: 11px; + font-size: 22px; + line-height: 32px; } .Layout .VPHome .VPHero .actions { - padding-top: 18px; + padding-top: 29px; + } + + /* The three buttons scale with the type above them, or they end up looking + * bigger than the headline they sit under. */ + .Layout .VPHome .VPHero .VPButton.medium { + padding: 0 18px; + font-size: 13px; + line-height: 34px; } - /* The cards. The icon is the one element that shrinks more than the rest: - * at 48px it is a tile of its own above the title, and the card is three - * lines of text under a picture. At 36px it reads as what it is — a mark on - * the card, not the card's subject. */ + /* The cards: 24px of padding, a 48px icon, 16/14 type. */ .Layout .VPHome .VPFeature .box { - padding: 16px; + padding: 22px; } .Layout .VPHome .VPFeature .icon { - margin-bottom: 12px; - width: 36px; - height: 36px; - font-size: 19px; + margin-bottom: 18px; + width: 43px; + height: 43px; + font-size: 22px; + } + + .Layout .VPHome .VPFeature .title { + font-size: 14.5px; + line-height: 22px; } .Layout .VPHome .VPFeature .details { + padding-top: 7px; + font-size: 13px; line-height: 22px; } - /* The samples button, set apart under the grid. Its rule above already - * gives it a divider and 68px of air; on one screen that reads as the same - * separation at 42px. */ + /* The samples block is this file's own, further up — same treatment, so it + * shrinks with the grid it sits under instead of growing relative to it. */ .Layout .VPHome .a2ui5-catalogues { - margin-top: 24px; - padding-top: 18px; + margin-top: 36px; + padding-top: 25px; } - .Layout .VPHome .a2ui5-catalogues .a2ui5-catalogues-links { - margin-top: 14px; + .Layout .VPHome .a2ui5-catalogues .a2ui5-catalogues-lead { + font-size: 13px; + line-height: 20px; } - /* And the gap below all of it. 128px under the last thing on a page is the - * theme assuming there is more page coming; here there is not, there is a - * footer. */ - .Layout .VPContent .VPHome { - margin-bottom: 36px; + .Layout .VPHome .a2ui5-catalogues .a2ui5-catalogues-links { + margin-top: 18px; } -} -/* The footer is outside `.VPHome`, so it takes its own rule — and it is not - * home-page-only: 32px above and below two lines of small grey text is the - * same overspend on every page. - * - * `:not(.has-sidebar)` is here for specificity, not for the selection: the - * theme hides the footer on sidebar pages anyway, so this matches every - * footer anyone ever sees, and it takes the rule to three units against the - * scoped `.VPFooter[data-v-…]`'s two. */ -.Layout .VPFooter:not(.has-sidebar) { - padding: 20px 24px; -} + .Layout .VPHome .a2ui5-catalogues .a2ui5-catalogues-links a { + padding: 7px 20px; + font-size: 13px; + } -@media (min-width: 768px) { - .Layout .VPFooter:not(.has-sidebar) { - padding: 20px 32px; + /* And the gap below all of it — the one number that is not nine tenths of + * the theme's, for the reason given above. */ + .Layout .VPContent .VPHome { + margin-bottom: 48px; } } diff --git a/docs/get_started/about.md b/docs/get_started/about.md index ba8abaf2..4590cc4f 100644 --- a/docs/get_started/about.md +++ b/docs/get_started/about.md @@ -1,5 +1,6 @@ --- outline: [2, 4] +description: What abap2UI5 is, on one page — UI5 apps written purely in ABAP, how the framework works, what it runs on, and where it fits. --- # In a Nutshell @@ -22,6 +23,12 @@ ENDCLASS. That's it — your first UI5 app is ready. (`client` is the single parameter of `main`, passed in by the framework — explained on the [Hello World](/get_started/hello_world) page.) +A finished app looks like any other UI5 app, because it is one — a selection screen, a table, a dialog, all of it built from the same single class: + +![An abap2UI5 app: a selection form above a table of invoices, with a dialog editing one row](/tutorials/walkthrough-preview.png) + +→ *The [Tutorial](/tutorials/overview) grows exactly this app in ten steps, each one a complete class you can run in the browser* + ## Background Since launching in 2023, abap2UI5 has grown from a small side project into a community-driven framework used by ABAP developers worldwide. The framework absorbs frontend complexity, so you can focus on business logic with your existing ABAP skills. @@ -40,6 +47,16 @@ Traditional UI5 development needs JavaScript expertise, frontend deployment, and Each app ships as an [abapGit](https://abapgit.org) project, so installation across systems needs no separate frontend deployment. +## How It Works + +The frontend is a UI5 shell that only renders. Your ABAP class builds a UI5 XML view, the framework sends it to the browser with the data already embedded in it, and every user interaction comes back as a fresh call into `main( )`. No OData service sits in between. + +Nothing survives on the server between two clicks, and that is deliberate: `z2ui5_if_app` inherits `if_serializable_object`, so the app's state travels with the roundtrip and is restored before `main( )` runs again. Each request is a new ABAP session holding your app exactly as the user left it — stateless like any other UI5 app, which is what makes it scale. For the few cases that need a pinned session — a classic enqueue, an open RFC connection — a [stateful mode](/cookbook/expert_more/statefulness) exists. + +Outside the SAP world this pattern has a name — *HTML Over-the-Wire*, the idea behind htmx, Hotwire and Phoenix LiveView. abap2UI5 applies it to UI5. + +→ *See [UI5 Over-the-Wire](/technical/concept) for the architecture, and [Behind the Scenes](/technical/how_it_all_works) for what happens on a single request* + ## Overview
@@ -49,15 +66,35 @@ abap2UI5 takes a "thin frontend" approach — all processing, logic, and data ha ### Performance abap2UI5 is fast. The frontend focuses only on UI rendering via the UI5 framework, while the ABAP backend handles all processing. Unlike traditional UI5 apps that need separate OData calls for each view, abap2UI5 embeds data directly in XML views — cutting network roundtrips and speeding up the response. +→ *See [Performance](/configuration/performance) for what to measure and what to tune* + ### Security abap2UI5 is secure by design. All business logic stays in the ABAP backend. The frontend receives only the data the backend embeds directly in XML views. Unlike traditional UI5 apps that expose OData endpoints, abap2UI5 delivers only what users need — no access to raw services or database queries from external tools. +Authentication is the ICF node's job, exactly as for any other service on your system, and the framework ships a Content-Security-Policy by default. Authorization stays yours: whatever the user sends still arrives from a browser, so check it in the app or on the service node, as you would in any other program. + +→ *See [Security](/configuration/security) for the endpoint, the CSP and what the framework does not do for you, and [Authorization](/configuration/authorization) for setting up checks* + ### System Footprint The framework has a small system footprint — essentially classes, interfaces, and a single draft table. The core stays minimal; optional add-ons provide extra functionality only when you need it. +→ *See [Add-ons](/advanced/addons) for the ecosystem around the core — layout variants, table maintenance, charts* + ### Transparency All source code lives publicly on GitHub. We discuss features and issues openly, publish technical blog posts that explain key concepts, and ship fixes quickly via abapGit. You'll always understand how the framework works and can confirm its behavior. +## Where It Fits + +abap2UI5 is built for business apps: worklists, forms, CRUD, dashboards, selection screens — the kind of thing you would otherwise write as a Selection Screen, an ALV report or a freestyle UI5 app. + +It is deliberately not built for everything. Three cases are a poor fit, and knowing them up front saves a prototype: + +- **Heavily interactive or real-time collaborative apps.** Every interaction that needs the server is a roundtrip. +- **Offline use and complex client-side behaviour.** The browser renders; it does not hold the application. +- **Teams that work strictly separately.** The app is one ABAP class — that is the point, and it means there is no frontend project for a frontend team to own. + +→ *See [Use Cases](/advanced/use_cases) for the on-stack, side-by-side and SaaS scenarios, and [UI5 Over-the-Wire](/technical/concept) for the reasoning behind the boundary* + ## Compatibility
@@ -75,12 +112,17 @@ Works with both ABAP Cloud and Standard ABAP: For systems on releases before 7.50 (down to 7.02), a separate downported version is available. +### UI5 Versions +The frontend is UI5 itself, loaded at bootstrap like it is for any other UI5 app. abap2UI5 bootstraps OpenUI5 from its public CDN by default; a single exit points it at SAPUI5, at a pinned version, or at the UI5 already delivered by your own system — which is what a system without internet access uses. `1.71` is the oldest supported release, and every change is tested against UI5 2.x as well. + +→ *See [UI5 Versions](/configuration/ui5_versions) for the distributions, and [Bootstrapping](/configuration/setup/ui5_bootstrapping) for choosing the source* + ## Enterprise Ready abap2UI5 combines SAP's UI5 framework with ABAP's backend capabilities, shaped for enterprise SAP environments. It runs smoothly across S/4HANA Public/Private Cloud, BTP ABAP Environment, and NetWeaver systems. ### Production Usage -Use abap2UI5 like any other UI5 app or ABAP program in production. Add the framework and your apps to a transport request to ship them. +Use abap2UI5 like any other UI5 app or ABAP program in production. Add the framework and your apps to a transport request to ship them. Updates ship as versioned releases with every change listed: see the [Release Notes](/resources/changelog), and the [Deprecations](/resources/deprecations) page for what is on its way out and what replaces it. ### Licensing Technically, abap2UI5 apps are standard UI5 freestyle apps. License them the same way you license other UI5 apps at your organization. abap2UI5 itself is MIT licensed (free for commercial use). @@ -99,6 +141,14 @@ Getting started is easy: → *See the [Quickstart Guide](/get_started/quickstart) for full instructions* +## Tooling + +None of it is required — an app is one class in your system, and ADT is enough. What exists is worth the ten minutes: a [linter](/advanced/linter) that reconstructs the UI5 view out of the ABAP that builds it and reports what UI5 does not have, without an SAP system; a [VS Code extension](/advanced/vscode) that runs the app next to the code on `F9`; and an [MCP server](/advanced/mcp_server) that lets an AI assistant build an app *and look at the result*. + +That last point is not a novelty: an app is a single ABAP class, in one language, that an assistant can also verify — which makes abap2UI5 unusually well suited to being written with one. + +→ *See [Tooling](/get_started/tooling) for the setup, and [Developing with AI](/get_started/ai) for the assistant workflow* + ## Community
@@ -116,3 +166,8 @@ Contributions are always welcome. Whether you fix bugs, build features, or impro Volunteers maintain abap2UI5. If you or your company benefits from the project, please consider sponsoring it. → *Read more about [sponsorship opportunities](/resources/sponsor)* + +### In Production Elsewhere +Companies, workshops and open-source projects already run on abap2UI5, with the system release and the use case named. + +→ *See [Who Uses abap2UI5?](/resources/who_uses) — and add your own scenario*