Single source of truth for agents working on abap2UI5 Samples — a collection of demo apps for the abap2UI5 framework. This file owns everything: the folder scheme, the compatibility model, the overview generation rules, and the ABAP code style / app-structure conventions.
These instructions OVERRIDE any default behavior and must be followed exactly.
This entire project is in English. All code, comments, commit messages, PR titles, PR descriptions, and any other text must be written in English.
- The PR title becomes the squash-merge commit subject — make it describe
the change. Before merging, replace any auto-generated title (e.g. a
branch name like
Claude/...-abc123) with a short descriptive English title that states what actually changed. - One topic per PR. A structural change (a generator, a gate, a workflow, this file) must not ride along in a PR titled for an unrelated sample — split it into its own PR so the history stays searchable.
Everything lives in one flat package (abapGit FOLDER_LOGIC=PREFIX,
STARTING_FOLDER=/src/): every sample is a class directly in src/, beside
z2ui5_cl_smp_app_000, the overview app (§3), which is an index and not a
sample. There are no subpackages, and no folders under src/ at all.
src/ "abap2UI5 - samples" every sample, flat — one class per sample, nothing else
node scripts/check-agents-structure.mjs (npm run check:agents, and the
agents_structure job on every pull request) holds the tree to that: it
refuses a folder under src/, and compares the quoted name above against the
<CTEXT> of src/package.devc.xml. A new package needs this section,
scripts/lib/scan-samples.mjs and that gate changed in the same commit —
otherwise the classes in it are in no catalogue and thirteen gates stay green
(see check-orphan-samples.mjs, which is the other half of that lesson).
src/01 ("samples") and src/00 ("system") were flattened away on
2026-09-22. src/01 held the portable samples and src/00/98 ("testing")
the apps held back by their purpose; the samples moved up into src/ and the
testing package went with its last app (§2). Two packages carrying one rule
each — is this portable and is this a demo — and after the clean-out of
2026-09-22 the answer to both is yes for everything in the tree, so the split
had nothing left to sort.
Nothing about a sample moved with it: class names never encoded the folder
(FOLDER_LOGIC=PREFIX), so this was a move and not a rename.
src/00/02 ("restricted - release/version") and src/00/99 ("obsolet") had
gone on 2026-08-12, 00/99 together with the samples it still held. Two
categories, not two policies: what made a sample restricted or obsolete is
unchanged, there is simply no package standing empty in the tree waiting for
the next one.
So a sample that plain OpenUI5 1.71 cannot run — a SAPUI5-only control
(sap.suite.*, sap.ui.comp.*, sap.viz.*, …), a control or property
introduced after UI5 1.71, or native JavaScript / CSS the sample would have to
ship — has no home in this repository today, and neither has a superseded
one. Do not park it in src/: every sample there must survive the 702
downport (§2). Either it belongs in
samples-stack or
samples-controls (§2), or the
category has to come back. Re-creating one is a deliberate, self-contained
change: add the package, put it into the tree above and into the §2 build
table in the same commit, or the checks below fail.
There is no on-premise-only package: main is installed on ABAP Cloud
systems as it is, so every sample in the repository must be ABAP Cloud ready.
A sample that needs on-premise-only ABAP does not belong in this repository.
src/00/97 ("experimental") was removed on 2026-09-14, and the fourteen
samples it held were promoted into what was then src/01:
Z2UI5_CL_SMP_APP_004, _052,
_122, _381, _468, _498, _499 and _504 … _510. That is the
maintainer decision §2 reserves for itself, taken by hand and recorded here —
not a sample graduating because it lints clean.
The package emptied itself in the process, and an empty one does not stay:
what it said — not finished yet — has no sample left to say it about. So
"experimental" is a verdict, not a folder today. A work-in-progress sample
has no package to park in: finish it and it goes into src/, or it stays out
of the repository until it is finished.
They spent two commits one level too high on the way, in a folder that has no
catalog at all — all fourteen were missing from the overview app and from
SAMPLES.md while every gate stayed green.
That no longer goes unreported: node scripts/check-orphan-samples.mjs
(npm run check:orphans, and the orphan_samples job on every pull request)
refuses a z2ui5_cl_smp_app_* class that does not sit directly in src/. It
is the one gate here that does not count tiles — which is why it is the
only one that could have caught this: the other thirteen all read the same
scan, and the scan never saw these fourteen. A ZZZ helper gets no tile either
and is fine; being skipped by a RULE is not the same as being skipped by where
the file happens to sit.
Z2UI5_CL_SMP_APP_<no> is the name; <no> alone is not. Numbers are handed
out inside this repository only, and the three sample repositories reuse each
other's freely — 493 is Z2UI5_CL_SMP_APP_493, Hello World, here, and
Z2UI5_CL_SMPS_APP_493, a classic FilterBar with variant management, in
samples-stack. So are 489 and
490. There is no global number space and there was never going to be one:
each repository numbers from its own sequence, and coordinating three of them
would buy nothing a prefix does not already give.
What follows, in prose anywhere — this file, the README, a commit message, a
comment: name a sample by its class, never by its number alone.
Z2UI5_CL_SMP_APP_143 and "sample 143" read the same to somebody who already
knows which repository they are in, and only the first one still reads
correctly to everybody else. The tables in a generated catalogue are exempt:
there the number is a link to the class file, which is the qualification.
01/03 "Control Library" is gone (2026-08-12), with all 32 of its samples.
1:1 rebuilds of UI5 demo kit samples are collected in
abap2UI5/samples-controls —
which rebuilds every official sample against its original view and gates each
port on that comparison — and keeping the same original rebuilt in both was
pure redundancy: 14 of the 32 were already ported there under the same demo kit
sample id, and 12 of the rest carried no sample id at all, only an entity URL,
so there was no original to be faithful to. The whole set was imported into
samples-controls' todo/ for triage before the packages were removed here and
every imported class got its verdict the same day; that staging folder was
deleted with the closed triage, so the per-sample verdicts are in
samples-controls' git history (todo/README.md at commit 37e77b6), not in
its tree.
Do not re-create a Control Library package, and do not add a demo kit rebuild
to this repository. A sample that rebuilds one specific demo kit original
belongs in samples-controls, full stop. What legitimately stays here is what
cannot live there, and it goes into src/ as an ordinary sample:
- a 1.71-safe variant of a sample whose samples-controls port keeps
post-1.71 members for 1:1 fidelity (declared
POST_171there) — this repository is downported to 702, so the restriction matters here and does not there; - a sample in samples-controls' hold-out set (
ui5/holdout.json), which is deliberately never ported there because it measures its generator; - a free-style control demo with no single demo kit original.
These exceptions are the Control Behaviour category (§4), and they are the
whole of it: samples that drive a control from the backend — expand a Panel or
switch a NavContainer page by ID, open the PDF viewer, step a Wizard — rather
than showing what the control is. The catalogue lists them; this file does not
count them, because the count goes stale the day a sample is added.
The category was called Control until 2026-08-18, which was the wrong
name for exactly this reason: it is the noun samples-controls owns, and a
reader who found a five-entry "Control" section in this repository's catalogue
had no way to tell it apart from the 300-entry control reference next door
except by reading all five. The entries were always legitimate; the heading
claimed a scope they never had. Control Behaviour says what they are and
keeps control as the search term. A new entry belongs here only if it passes
one of the three tests above — otherwise it is a demo kit rebuild and belongs
in samples-controls, full stop.
A test or scaffolding app is not written at all unless a unit test in abap2UI5 cannot make the same statement — which since the 2026-09-22 clean-out (§2) is nearly always the wrong way round: the testing package went from 41 apps to none. There is no experimental package any more either (§1).
main is the default branch and the only branch anyone commits to. It is
installed both on standard on-premise systems and on ABAP Cloud, so it is
checked against both releases on every pull request. 702 is the one derived
branch, generated from main by publish-702.
Every build sees the same tree:
| Build (workflow) | What it does | Sees src/ |
|---|---|---|
abap-standard |
abaplint ./abaplint.jsonc (syntax v750) |
✅ |
abap-cloud |
abaplint abap_cloud.jsonc (syntax Cloud) |
✅ |
abap-702 |
npm run downport → abaplint abap_702.jsonc |
✅ |
Nothing is stripped any more. The 702 build used to delete src/00 before
downporting, because the samples held back by their purpose had no business on
a branch published for old systems. That package is gone (§1) and the downport
is a pure transformation now: the 702 branch carries every class main
carries. With it went scripts/check-strip-lists.mjs and its CI job, which
existed to keep the removal spelled identically in package.json and in the
table above — there is no list left for the two to disagree about.
The clean-out that made this possible is recorded below: src/00/98 went from
41 apps to none, and src/00/01 "context" had gone on 2026-08-20 with the
two classes it held, z2ui5_cl_smp_context and z2ui5_cx_smp_error. What they
offered was generic RTTI, message and conversion helpers, and a sample that
reaches for one stops being a single readable snippet — the thing a sample is
for. Every caller carries the few lines it actually used.
Nothing is suppressed either. abaplint.jsonc has no noIssues list:
every class under src/ is really linted, by abap-standard, abap-cloud and
abap-702 alike. Do not introduce one to make a sample pass — a path listed
there stops being checked at all, silently.
The abap-702 transformation also produces the derived branch 702
(publish-702, on every push to main). There is no cloud branch: ABAP Cloud
systems install main itself, and abap-cloud is a check on the pull request,
not a publish step. The 702 branch carries the root abaplint.jsonc of main
unchanged — the release-specific configs stay under .github/abaplint/ and are
passed to abaplint explicitly.
Copying abap_702.jsonc over the root config would make the abaplint GitHub
App lint the derived branch at syntax v702: the app resolves a dependency
from the installed repository's default branch and ignores the branch field,
so it would check the downported samples against the un-downported framework
in abap2UI5/abap2UI5@main and report every type declared there with
WITH EMPTY KEY as unknown. The 7.02 check itself is not lost — it runs in
abap-702 on every pull request, and again in publish-702 before the push.
Consequence of the rule: a class may only live in src/ if it is ABAP
Cloud ready AND downportable to 7.02 and runs on plain OpenUI5 1.71 without
any restriction. There is no second package to fall back on: a sample held
back by its maturity lost its home on 2026-09-14 (src/00/97
"experimental", §1) and one held back by its purpose on 2026-09-22
(src/00/98 "testing", below).
The way out of src/00/98 was deletion, and it was taken on 2026-09-22.
The package held 41 apps; all of them are gone. Not because they were wrong,
and not to make room — because the framework's own unit tests now assert,
headlessly and on every push, exactly what each of those apps asserted by
hand in a browser. Every bare number below is a Z2UI5_CL_SMP_APP_<no> of
this repository — the one place in this file where the numbers stand alone,
because a list of forty class names says nothing forty numbers do not (§1).
The framework wrote them in: z2ui5_cl_ui5_srv_model's
test class names samples 118, 138, 184, 190, 194, 199, 212,
332, 334, 338, 339, 343, 344, 347 in its own fixture comments,
z2ui5_cl_ui5_app_cont names 335 and 338, z2ui5_cl_ui5_handler names
340. The rest went with them by shape: the reference-identity family
(328/329, 331, 333, 336, 337, 342, 345, 348, 349) against
aliases_know_owner, shared_one_canonical, both_refs_back_on_table,
alias_stays_on_struct, alias_repointed_survives and the app_cont draft
roundtrips; the host/sub-app scaffolds (117/126, 131/132, 185,
191, 195, 211) against refresh_finds_late_obj, class_swap_* and
load_by_app_after_swap; the binding shapes (094) against the
z2ui5_cl_ui5_srv_bind tests structure_levels, reference_deref and
helper_attribute; the frontend actions (353, 443, 446, 447) against
test_follow_up_action_ctrl / test_ctrl_global_opt on the ABAP side and
node/tests/frontendAction.spec.js, messages.spec.js, timer.spec.js,
deviceModel.spec.js on the JavaScript side. 086 went as well: it renders
a value an app 085 was supposed to set, and no 085 has existed here for
a long time.
The last one went with the package: Z2UI5_CL_SMP_APP_324. It called
POPUP_TO_CONFIRM dynamically to provoke "Sending of dynpro SAPLSPO1 0500
not possible" — a failure that needs a real dynpro runtime, which no unit
test in either repository has. It was the one app the 2026-09-22 clean-out
left standing, and it was deleted with src/00 on the same day the tree was
flattened (§1): one app is not a package, and a testing app in the middle of
the catalogue is a sample a reader would copy.
The rule it stood for is unchanged and is now the whole of it: if a unit test in abap2UI5 can make the statement, the unit test is the place to make it — and if it cannot, that is an argument for a unit test the framework does not have yet, not for an app here. This repository is demos.
A sample restricted by UI5 — a SAPUI5-only control (sap.suite.*,
sap.ui.comp.*, sap.viz.*, sap.ui.vk/vbm, sap.ndc,
sap.ui.richtexteditor, …), a control or property introduced after UI5 1.71,
or a runtime it cannot ship (native JavaScript / CSS / HTML) — and one that is
superseded or deprecated have no package here any more (§1), and there is
no longer any folder to file one under to get it in.
A sample that needs something the system provides does not belong here at
all. Those live in
abap2UI5/samples-stack, one package per
technology: an OData service, smart controls, a RAP business object, a stateful
session, an APC channel, the MIME repository, and the Fiori Launchpad
(src/09 there — the demos that read startup parameters, set the shell title and
navigate cross-app, moved out of the restricted package on 2026-08-12).
One deliberate exception (maintainer decision, 2026-09-30): the clipboard
samples Z2UI5_CL_SMP_APP_538 and Z2UI5_CL_SMP_APP_539. Copy and paste
in a table is built on sap.m.plugins.CellSelector (@since 1.119),
CopyProvider (@since 1.110) and PasteProvider (@since 1.91), which have no
1.71 equivalent, and on the CopyProvider's extractData callback that
abap2UI5 ships as z2ui5/model/clipboard. They sit in src/ like every
other sample and say what they need where a reader looks first: (UI5 1.119+)
in the DESCRIPT, the @summary and the intro MessageStrip. The ABAP is held
to all three builds like every other class; only the linter's two version
rules are lifted for exactly these two classes (abap2ui5lint.jsonc). This is
not a category — a further post-1.71 sample needs the same decision again.
A sample qualifies for src/ only if none of the above restrictions
apply: OpenUI5-compatible, ABAP-Cloud-ready, standalone, every control and
property available since UI5 1.71 (16 Jan 2020) and not deprecated, no native
JS, not a test, finished and clean. "Old" is not enough and "non-deprecated" is
not enough either — a deprecated control and a post-1.71 one both disqualify a
sample from this repository, and neither has a package to fall back on any
more (§1).
ABAP Cloud readiness is not a sorting criterion at all — it is a precondition
for every sample in the repository (§1).
z2ui5_cl_smp_app_000 is the overview app — a generated index page that
lists every sample in the repository. It is not a Fiori Launchpad app, despite
the name of the generator that writes it (npm run launchpad, §4). The demos
that run inside a real Fiori Launchpad are not in this repository at all — they
live in abap2UI5/samples-stack under
src/09 (§2).
| App class | Lives in | Title | Mirrors |
|---|---|---|---|
z2ui5_cl_smp_app_000 |
src/ |
abap2UI5 - Samples |
src/** |
It is the only one, and since the tree was flattened (§1) it mirrors all of
it — there is no package left whose samples are reachable by class name only.
An extended overview app existed once (z2ui5_cl_sample_app_g01, mirroring the
restricted area, cross-linked with this one); it was removed when the extended
samples were reorganised. Should a second one ever be needed, it comes back as
a second target in scripts/generate-launchpad.mjs and a second row above.
Its shape: a get_catalog( ) method returning a flat table of tiles - one
group per stage of the learning path (scripts/lib/learning-path.json, the
same six stages catalogue.json publishes and the catalogue page draws), the
stage's blurb on the first tile of each group (intro), rendered once under
the group title - and a view_display( ) that loops the catalog, emitting one
link (header + optional sub) per tile, followed by a sap-icon://source-code core:Icon that
opens that sample's ABAP class on GitHub (source_url( ) over the tile's
path, wired client-side through open_url( ) like the header buttons — a
Button carries no href). It is deliberately an icon and not a transparent
Button: a Button brings its own height (2rem even in compact density) and
would set the line height of every row, while the icon is as tall as the text
beside it — which is what keeps the list tight. Around that list it renders a
fixed frame: two header rows (below) and an empty vbox( height = 4rem )
after the last tile so the list does not end glued to the page bottom.
The page carries no content header of its own — both rows are built by hand:
render_header( )puts aBarinto the page'scustomHeader, so the row can be split into a left and a right half:contentLeft— the back button and the app title, i.e. what the stock header would render on its own. APagerenders either its own header or a custom one, sotitle/navbuttonpress/shownavbuttonare gone from thepage( )call and the backButton(sap-icon://nav-back,visible = check_app_prev_stack( ),press = _event_nav_app_leave( )) is built here.contentRight— the three sample repositories of the abap2UI5 family, then a gap, then the two entries that leave the system: documentation and GitHub. The gap is the point: the three open an app, the two open a site. It rides on the first icon of the second group (group_startofheader_button( ), a wider begin margin), not on aToolbarSeparator: asap.m.Baron 1.71 lays its children out in normal flow, so a block-level separator starts a new line that the bar'soverflow: hiddencuts away — which is how the documentation and GitHub icons once vanished on 1.71.
render_sub_header( )puts anOverflowToolbarintosubHeaderand holds theSearchField(24rem).
There is no intro text on the page. It used to be a MessageStrip above
the list — tile count, the source-code icon, the Ctrl+F12 developer tools,
the (A) / (C) markers — which pushed the first samples off the screen; it
then moved behind an info icon in the header, and on 2026-08-13 it was dropped
altogether with that icon. The page explains itself through its tooltips.
Every abap2UI5 overview app renders the same entries — here
(render_header( ) / header_button( )), in
samples-controls and in
samples-stack. Five icons, always
in this order. header_button( ) takes each entry's name and descr
separately: the tooltip is <name> - <descr>, and the name alone titles the
popover of an uninstalled repository. The names are the italic ones below.
There used to be a sixth entry in front, sap-icon://home for the framework's
start page (z2ui5_cl_app_startup) — dropped from all three overviews on
2026-08-13: they list samples, and the start page is not one.
| Icon | Target | Repository |
|---|---|---|
sap-icon://lightbulb |
z2ui5_cl_smp_app_000 |
abap2UI5/samples — Samples |
sap-icon://palette |
z2ui5_cl_smpc_app_000 |
abap2UI5/samples-controls — Control Samples |
sap-icon://database |
z2ui5_cl_smps_app_000 |
abap2UI5/samples-stack — Stack Samples |
sap-icon://learning-assistant |
— | https://abap2UI5.org |
sap-icon://globe |
— | the repository the app itself lives in |
The repository entries lead to an app inside the system, the last two lead
out of it, and every overview shows that split — this one by the gap on the
first icon of the second group in its header Bar's contentRight
(above), samples-controls and samples-stack by a ToolbarSpacer
(width = 1rem) between the groups in their single-row headerContent. The
GitHub entry is not sap-icon://source-code: in the shared header that
icon is reserved for the per-sample source links an overview renders in its
list.
Here the entries are core:Icons, not Buttons (header_button( )), and
the reason is the colour: an icon carries one (color), a Button on 1.71
does not — the coloured sap.m.ButtonType values (Critical, Neutral, …)
are 1.73+. There are two states, active and inactive, and nothing in
between:
| Entry | Colour | Press |
|---|---|---|
| the overview app is on this system | default (active) | cs_event-nav into it |
| it is not on this system | default (active) | cs_event-install → install_display( ) |
documentation / GitHub (no class) |
default (active) | opens the site |
the app you are in (here) |
Neutral (inactive) |
none |
Grey therefore marks exactly one entry — the overview you are already in, which is the only one with nowhere to go. A repository that is not installed looks like any other: it is a destination, the press just explains what has to happen first. The tooltip says so before the click does.
A missing repository stays clickable. Instead of dropping the user on
GitHub without a word, the press fires cs_event-install carrying the class,
the GitHub URL and the repository name; install_display( )
opens a Popover on the pressed icon — hence every repository icon carries
its class name as id — that says what is missing, that abapGit installs it,
and links to the repository. Only entries without a class (documentation,
GitHub) still open their site directly through open_url( ).
All three overviews carry this header, layout included (2026-08-13): the
Bar in the page's customHeader, back button and title on the left, the
five icons with their gap on the right, the two colour states and the
install popover. samples-controls builds it in
scripts/generate-overview.mjs (its overview class is generated — never edit
the class), samples-stack in z2ui5_cl_smps_app_000. All three build it with
z2ui5_cl_ui5_view_builder, which renders an empty attribute rather than
skipping it (color="" is no valid IconColor), so the optional ones are
added under an IF. What stays local to a repository is
what sits around the family entries — this one's SearchField sub-header,
samples-controls' filter toolbar, samples-stack's Regenerate Demo Data button
(first in its contentRight, before a separator). A change to an icon, the
order, the colours or the press behaviour belongs in all three repositories in
the same change.
Each repository is installed on its own, so every icon decides for itself:
class_installed( ) instantiates the target class, and on this system the
press is cs_event-nav with the class name as its event argument — on_event
hands it to app_call( ), which navigates with nav_app_call( ), and the back
button returns to the overview. What happens when it is not on this system, and
for the overview you are already in, is the table above.
A repository that renames its overview app is installed under both names in
the wild for a while, so header_button( ) takes an optional class_old and
falls back to it when the current name is not on the system —
z2ui5_cl_smpc_app_overview for samples-controls (renamed again 2026-08),
z2ui5_cl_demo_app_g00 for this repository. Add the old name there when an
overview app is renamed; drop it again once the rename is old enough.
Keep the three headers in sync. A change to the order, the icons or the behaviour belongs in all three repositories in the same change.
The search field filters the tile list: its search event (Enter, or the
clear button) fires SEARCH, which re-renders the view with catalog_filter( )
applied — a case-insensitive contains-match against each tile's header, sub,
keywords (never rendered, §4) and app class name — and then replays the
focus into the search field.
That focus wire is focus_search( ), a set_focus follow-up action with the
cursor at the end of what is already typed, and it runs on every display of
the page: the overview opens with the cursor in the filter, so the first key
you press searches, and after a filter roundtrip typing simply continues. On
the way back from a sample it is queued before scroll_restore( ) —
focusing a control can scroll it into view, and the restored scroll position is
the one that must survive.
The info popover keeps naming the total tile count (the unfiltered
catalog), an empty filter result renders a No sample matches the filter. text
instead of tiles, and the filter value survives navigation into a sample and
back (it is a serialized public attribute).
An H3 section title is emitted whenever the group changes — but only when
there is more than one group to tell apart. group_titles_needed( ) decides
that by comparing every tile's group against the first one; with the whole
catalog in a single package the heading would only repeat the page title, so it
is left out — and because nothing then separates the first block from the
header rows above it, that first block opens with the same sapUiSmallMarginTop
the other blocks carry. The title and the stage blurb under it go into one
VBox, and that VBox carries the margins
(sapUiSmallMarginBegin sapUiSmallMarginEnd sapUiSmallMarginTop sapUiTinyMarginBottom)
— not the two controls themselves. Both sap.m.Title and sap.m.Text are
display: inline-block, so as siblings of the page they shared a line whenever
the blurb happened to fit beside the heading: a long blurb wrapped below its
title, a short one sat next to it, and no two groups looked alike. The VBox is
what stacks them, and its begin margin is what puts the heading in the same
column as the rows, the blurb and the legend instead of one rem to the left of
all three. Keep that check free of table expressions (t_catalog[ 1 ]): the
702 downport hoists them out of their guarding condition, so an IS NOT INITIAL
guard around one does not survive the transformation.
Navigation is by class name: the tile press event is the app value, on_event
(after handling SEARCH, see above)
does to_upper( ) → CREATE OBJECT TYPE (classname) → nav_app_call( ),
wrapped in a TRY/CATCH cx_root so a catalog entry whose class is missing
from the system does not dump — a safety net, not a substitute for keeping
the catalog correct. on_event also records the scroll position, which
scroll_restore( ) replays via follow_up_action( cs_event-scroll_to ) on
check_on_navigated( ), so returning from a sample lands where the user left.
Within a group, view_display( ) also inserts a blank line between blocks:
consecutive tiles whose header shares the same base name form one block, and a
new block (first row gets sapUiSmallMarginTop) starts when the base changes.
The base is the header with a trailing Roman numeral removed
(header_base( )) - the category - so Binding, Binding I … Binding VIII
render as one block, then a gap, then the Event block, and so on. (A controls
section that blocked by first letter existed while the Control Library package
did; it went with that package, §1.) Under the list the app prints the legend of the
capability markers some titles end in (c_legend, written by the generator
from scripts/lib/markers.mjs - the same legend SAMPLES.md and catalogue.json
carry, §12). All links of
a block share the same width — the estimated render width of the widest header in
the block plus roughly one space, precomputed by block_widths( ) /
header_width( ) — so the sub descriptions of a block line up exactly
underneath each other in one column, directly next to the links.
z2ui5_cl_smp_app_000_0, the old "classic" overview app, is gone with the
00/99 package it was retired to (§1). Do not bring it back — smp_app_000 is
the only overview app, and it is generated.
Reaching the overview app costs an installed framework, an abapGit pull and an HTTP handler. Before that, the repository is a flat folder of classes whose names encode nothing, and the question a visitor arrives with — is there a sample for X? — has no answer here.
SAMPLES.md answers it. Every app, its description, its
@keywords (the app keeps them for its search box; on a page the reader is
the search box, so they are rendered), the @docs chapter that explains what
it demonstrates, and a link to the source. Written by
scripts/generate-samples-md.mjs from the same scan as the overview app —
scripts/lib/scan-samples.mjs, which is the single place that knows what counts
as a sample, where its title comes from and which classes are hidden helpers.
Two copies of that would drift silently: the app and the page would simply
disagree about what this repository contains, and nothing would fail.
Three things it shows that the app does not, on purpose:
| Why | |
|---|---|
the ZZZ helper apps |
they must not get a tile — but a catalogue claiming to account for the tree has to say they exist |
the @keywords |
never rendered in the app (§4); here they are what Ctrl+F finds |
the @docs link |
the chapter that explains the pattern the sample demonstrates (§4) — the app has no room for it, and a page does |
The 702 branch carries its own: npm run downport regenerates the file after
the transformation, so the copy on that branch lists what that branch actually
ships — which since the strip list went (§2) is everything.
Do not hand-edit it — it is regenerated by npm run launchpad along with
the overview app and catalogue.json (below), and the catalogues job of
check-docs.yaml checks the three together (§4).
It has readers outside this repository, and they parse the ROWS. Two of them today:
mcp-server lib/examples.mjs |
the examples MCP tool — an agent asking "has somebody already built X" |
docs scripts/link-samples.mjs |
the Working Samples block under a cookbook page |
Both read this file live rather than a generated index, so what they see is
always what it says — and both match a row with a regex. Changing the shape
of a row breaks them silently. Adding the @docs line as a second
<br><sub> block did exactly that: a parser expecting one small-type block
matched no rows at all, and the examples tool would have answered "no sample
for that" to every query — no error, no log, just an agent taking it at face
value and writing the app from scratch.
So a change to row( ) in generate-samples-md.mjs is a change to their input.
Grep both repositories for the row regex before merging one, and give them a
fixture with the new shape.
The fourth view of the one catalogue, and the first one addressed to a
machine. The two readers above parse SAMPLES.md rows with a regex because
nothing better existed; an AI agent that has just cloned this repository was
in the same position. catalogue.json at the repository
root is the structured answer: one entry per sample — class, folder,
category, learning-path stage, keywords, @summary, @docs links — plus a
header naming the repository, its place in the three-repository family, and
the number-collision caveat (§1, "Sample numbers are per repository") encoded
as data rather than prose. Written by scripts/generate-catalogue.mjs from
the same scan as the other three views (scripts/lib/scan-samples.mjs)
and the learning-path file it also validates
(scripts/lib/learning-path.json), so it cannot disagree with any of them.
It is committed, and it carries no linter pass — that is one decision, not
two. Its reader is a clone or a raw fetch, which no deploy ever runs for, so
a file that only exists after a build step does not exist for them at all; and
staying offline and dependency-free is what lets it be generated anywhere,
including in a plain-node CI job. The derived facts that would need the linter
live beside it in catalogue-derived.json (see "The catalogue" below). What
keeps the committed copy honest is the freshness gate:
npm run check:catalogue (in npm run check, and in the catalogues job of
check-docs.yaml) runs the generator with --check and fails when the file is
stale.
Do not hand-edit it — npm run launchpad rewrites it (or
npm run catalogue for this file alone); change the facts on the classes, as
always (§4).
One exercise per sample of the learning path's first stage (Start here,
Basics I–VII), for the playground's lesson bar: a task in a sentence or
two, a hint, and a check — patterns the rebuilt view XML must match
(view), patterns the ABAP must match (source) or no longer match
(sourceNot), and the least number of unit tests that must run green
(tests). The playground (abap2UI5/browser-playground, writeLessons( ) in
tools/build-site.mjs) reads it from the commit it pins and shows the task
under "Lesson n of 7", with Check and Hint beside it.
Editorial, like learning-path.json beside it, and kept out of
catalogue.json on purpose: that file's shape is a published contract
(check-catalogue-contract.mjs). npm run check:exercises (in
npm run check) holds it to one exercise per Start-here class and none for
any other, patterns that compile, and a sample that does not already pass its
own source checks. A change to a Start-here sample can break its exercise
— a renamed attribute or event in a pattern — and that gate is where it shows.
Treat the get_catalog( ) table as a generated mirror of the folder
tree, never as free-form data. Whenever you add, remove, or move a sample —
or change a class's description — regenerate the catalog in the same change.
Nothing regenerates it for you. The catalogues job of check-docs.yaml
runs the generators with --check on every pull request and on main, and a
stale catalog fails it with the command to run — so regenerate and commit the
result with the change that made it stale. Read that diff before you commit
it: it is a real change to what the overview offers (a class that stops
matching the sample naming scheme shows up there as a deleted tile). Until
2026-09-27 a publish-overview-apps workflow committed the regenerated files
onto the pull request branch itself; the runs that commit started waited for a
maintainer's approval and left the pull request blocked, so it went.
Do not hand-edit the catalog. Run the generator, which scans the folders and
class descriptions, rewrites the get_catalog( ) block and writes SAMPLES.md
(§3) from the same scan:
npm run launchpad # → generate-launchpad.mjs && generate-samples-md.mjs
npx abaplint # must report 0 issues
Both outputs come from scripts/lib/scan-samples.mjs, which implements every
rule below — that is the file to edit when a rule changes, never the generated
ABAP or markdown. The two generators only render: how a tile is written as an
ABAP literal (generate-launchpad.mjs, which also decides the groups: the
stages of scripts/lib/learning-path.json, through
scripts/lib/learning-path.mjs, the one reader generate-catalogue.mjs uses
too) and how it is written as a table row (generate-samples-md.mjs).
One row per app, and every row names every field - intro is the
stage's blurb on the first tile of a group and intro = `` on every
other, keywords is written empty if a class ever lacks the comment line. A
row that leaves a field out is initial there on 7.40+, but the 702 branch is
the abaplint downport, which builds every row of a `VALUE` in one work area
it never clears - a left-out `intro` repeated the first tile's blurb under
every tile of its group (§10, VALUE #( ) formatting):
( group = `<stage title>` header = `<display title>` sub = `<short description>` keywords = `<extra search terms>` intro = `<stage blurb, first tile of the group only>` path = `<folder>` app = `<class name, lowercase>` )| Field | Meaning / rule |
|---|---|
group |
The title of the learning-path stage the tile's category belongs to (scripts/lib/learning-path.json; the category is the header without its Roman numeral). Becomes the H3 section title (rendered once, when the group changes). Generated - a category no stage names fails the generator rather than landing in a group of its own. |
intro |
The stage's blurb, on the first tile of each group and empty on every other; the app renders it once under the group title. Generated from the same file. |
header |
Link text shown to the user. Derived from the class short text (see below). |
sub |
Short description shown next to the link. Derived from the class short text (see below). May be empty ( ``) → then only the link is rendered. |
keywords |
Never rendered — search only. Extra terms so a sample is found by words that do not fit into the 60 characters of its DESCRIPT (see below). Required on every tile — npm run launchpad refuses an area's overview app if one of its tiles has no @keywords line. Three readers depend on them and all three fail the same silent way (the sample stays listed, stays correct, and never comes up): the overview app's search box, Ctrl+F on SAMPLES.md, and an agent asking whether a sample for X exists. ZZZ helpers are exempt — a helper is reached BY another sample, never looked up. |
path |
The class's folder relative to the repository root (src, for every sample since §1 flattened the tree). Generated, because the class name does not encode the folder — source_url( ) builds the GitHub link of the sample from it. |
app |
The app's class name in lowercase (folder-independent). Drives navigation. |
keywords comes from a plain comment line on the class, the first line of
the *.clas.abap (above an ABAP Doc block, if the class has one), lowercase and
space-separated:
" @keywords f4 search help suggestion input dialog select
CLASS z2ui5_cl_smp_app_009 DEFINITION PUBLIC.It is a plain " comment on purpose — an unknown "! @tag is reported by the
extended check (SLIN/ATC). Put there what a newcomer would type but the visible
text cannot hold: synonyms (f4 for value help, alv for the grid table),
control names the sample uses (combobox, facetfilter, progressindicator),
and the abap2UI5 API it demonstrates (nav_app_call, binding_call,
control_by_id) — every framework cs_event-* constant the code passes and
every curated client method it calls must be among them, which
npm run check:api-keywords holds (§5). Four to eight terms, no backticks. The line is optional — a
sample without one is simply found by its header, sub and class name.
@summary is the sentence under the title, a second comment line directly
under @keywords — one sentence saying what the sample SHOWS:
" @keywords f4 search help suggestion input dialog select
" @summary The value help, both halves: suggestions while typing and the F4 dialog behind the field, over the same data.
CLASS z2ui5_cl_smp_app_009 DEFINITION PUBLIC.The two lines answer the two halves of one question. @keywords decides
whether somebody finds the sample; @summary decides whether they can tell
it is the one they want — which a 60-character DESCRIPT cannot ("Popup -
change a popup control from the backend" names the thing and stops). It is
rendered in SAMPLES.md directly under the row title, in normal type:
everything else in the row is metadata, this is its content.
Required on every tile, and required together: npm run launchpad
refuses an overview app whose tile has no @summary, and refuses any sample
carrying one of the two lines without the other. ZZZ helpers are exempt, as
with @keywords.
The gate is npm run check:keywords (scripts/check-keywords.mjs, and the
check-keywords workflow on every pull request). The generator's refusal above
is not one: npm run launchpad rewrites the tree, so it is not something a
pull request or npm run check can call, and the one workflow that does run it
regenerates and pushes — a missing line surfaces there as a job that failed
after the catalogue was half rebuilt. The gate also holds three things the
generator never sees, because it only ever looked at what becomes a tile: that
the @keywords line is the first line of the file (one further down is one
a reader scrolls past and a scanner reading the head of a file misses), that
the terms are lowercase and at least three of them. 104 classes carried the
two lines with nothing checking them; both sibling repositories gated
theirs.
Who is held to it is decided from the tree, never from a list: every sample
under src/, plus the overview app itself; not the ZZZ helpers (a helper is
reached BY a sample, never looked up). The gate names only what it exempts, so
a package that came or went needed no edit there — it survived src/00/97
being removed and the flattening of the tree (§1) untouched. A list would need
maintaining and would rot; this cannot.
Write it, do not derive it. The sibling repositories can: samples-controls
fetches the demo kit's own sentence (ui5/descriptions.json) and
samples-stack derives half of its metadata from the package scheme. Here
there is no upstream to quote — these apps were written for this repository —
so the line is the author's, which is exactly why it needs a gate: nothing
else fails when it is missing. Say what the sample demonstrates and what it is
good for, not which controls it happens to contain.
@docs is the way back to the documentation, a third optional comment
line under @summary, holding one or more full URLs into
https://abap2ui5.github.io/docs/:
" @keywords f4 search help suggestion input dialog select
" @summary The value help, both halves: suggestions while typing and the F4 dialog behind the field, over the same data.
" @docs https://abap2ui5.github.io/docs/cookbook/expert_more/value_help
CLASS z2ui5_cl_smp_app_009 DEFINITION PUBLIC.It is rendered in SAMPLES.md (never in the app — the tile has no room, and a
reader who is already inside the overview is not looking for a link out).
Full URLs rather than paths, because the line has to be useful where somebody
actually meets it: a search engine drops people into a class, and the code was
all they got.
Do not add one by hand. The pairing is declared on the documentation side —
a cookbook page lists its samples in frontmatter, and scripts/link-samples.mjs
in abap2UI5/docs generates the block of
sample links on the page and fails when a class it links to does not point
back. Adding a line here that no page declares makes that check red. Add the
page's samples: entry first; this line follows from it.
The gate is npm run check:docs-links (scripts/check-docs-links.mjs, and
the check-docs-links workflow on every pull request). It verifies both halves
of a line: that the page exists — docs/<path>.md in abap2UI5/docs, and
the #anchor when there is one — and that the page names the class back in
its samples: frontmatter.
That second half is the check quoted above, run from this side. It existed only
over there, which meant a pull request HERE could add a stale or invented link
and stay green until somebody regenerated the documentation; and the first half
existed nowhere at all. The scan refuses a URL that is not on the documentation
site, which catches a typo in the host and nothing whatsoever about the
path — and 95 classes carry one of these lines. Nothing fails when a page is
renamed: the class compiles, SAMPLES.md renders the link, and it 404s for
every reader who follows it.
It reads the documentation the way check-app-rules reads the shared rule set,
and degrades the same way: an abap2UI5/docs checkout next to this one first
($DOCS_HOME, .docs, ../docs) so a developer with the ecosystem cloned is
checked offline and in a second; otherwise raw.githubusercontent.com, one
request per page; otherwise it says so and passes. A gate must not go red
because github.com is unreachable, and must not claim to have verified what it
did not.
header and sub come from the class, not from hand-written labels. The
source of truth is the app class's abapGit short text <DESCRIPT> in its
*.clas.xml, written in the format header - sub:
- Split the DESCRIPT on the first
` - `(space-hyphen-space): the part before isheader, the part after issub(which may itself contain-). - No
-at all →header= the whole DESCRIPT,sub= empty. - Unescape XML entities (
&→&, etc.) when copying into the ABAP literal.
When regenerating, re-read every class's <DESCRIPT> — the descriptions are
maintained on the classes and change there, so never carry header/sub over
from the old catalog.
With the whole catalog in a single package there is no group heading (§3), so
the header is the category a reader sees, repeated down the page as the
link text. It is also the cheapest search term: typing popup filters the
list to the popup samples. Keep the set small, and keep every entry a word a
newcomer would actually type:
| Header | What belongs in it |
|---|---|
AI |
an assistant inside the app — a chat, an explanation of the data on screen — answered by a provider method a real LLM replaces. Samples here run without one; the ones calling a real model need an endpoint and live in samples-stack |
Basics I … VII |
the entry point — first app, lifecycle, the minimum loop, and what you reach for around it (the developer tools, a unit test on the app's own logic, the translation of its texts). The only numbered series: the Roman numeral orders them as a learning path (rule 5 sorts by header), and header_base( ) still renders them as one block |
Binding |
_bind( ), binding syntax, UI5 model types, the model itself |
Browser |
the browser page and tab: URL, title, favicon, reload, clipboard, storage, logout |
Control Behaviour |
one UI5 control is the topic — how it behaves and how the backend drives it, typically by calling its methods by ID. Not a control reference: that is samples-controls, and the header says so (§1) |
CSS |
own styles shipped with the view |
Device |
camera, geolocation, device model, frontend info |
Event |
_event( ), t_arg, keyboard shortcuts, event defaults |
File |
upload and download |
Focus / Scroll |
cursor and scroll position |
Formatter |
the curated JS formatters abap2UI5 ships |
Grid Table |
sap.ui.table.Table — never ui.Table |
Hash |
the URL hash and the app state: hash_set / hash_replace / hash_back, the routing modes (FRESH restarts the app, KEEP returns to its state), app_state_set_active / app_state_get_href — what Back, a bookmark, a reload and a shared link restore |
List / Table / Tree |
sap.m.List / sap.m.Table / sap.m.Tree |
Menu / Popover / Popup |
menus, popovers, dialogs |
Message |
MessageBox, MessageToast, MessageView, message model |
Navigation |
nav_app_call( ) / nav_app_leave( ) between apps |
Nested View |
nest_view_display( ), FlexibleColumnLayout |
Templating |
views generated at runtime (template:repeat) |
Timer |
client timers driving the backend |
Do not invent a catch-all (More, Function, Misc, Other) — those
existed and were dissolved on 2026-08-13 because nobody searches for them. A
new header is justified when at least two samples share a topic none of the
above covers; add it to the table in the same change.
Rules for the sub:
- Title Case, a short noun phrase, max 60 characters for the whole DESCRIPT — that is the hard limit of the ABAP class short text.
- Name the control or the API the sample is about (
FlexibleColumnLayout,SearchField,CustomTreeItem,setSizeLimit,nav_app_call,template:repeat). This is what makes the sample findable — the search matchesheader,suband the class name, nothing else. - Do not echo the header (
Control Behaviour - Wizard Control,Popup - Value Help with Popups). - Describe what the sample shows, not the mechanism it happens to use, when
the two differ — a Menu demo is
Menu - …, even if its point iscore:require.
- One catalog, and everything is in it.
src/is one flat package (§1), so every app in the tree belongs insmp_app_000— there is no second overview and no package whose apps are counted and listed nowhere. - Each app appears exactly once, and every demo app physically present is
listed (no missing tiles) — except hidden helper apps: a class
whose
<DESCRIPT>header isZZZ(e.g.ZZZ - called by SubApp I) is only ever called by another app and must not get a tile. It stays in the folder (and is checked by abaplint), just not shown in the overview. group== the learning-path stage of the tile's category. The stage comes fromscripts/lib/learning-path.jsonthrough the tile's category (its header without the Roman numeral); a category that no stage names fails the generator, the same rulecatalogue.jsonis held to. Renaming a stage's title there renames the group everywhere.- Groups follow the learning path. Emit the stages in the order the file
lists them - the order somebody learns them in, which is a teaching
decision and not the alphabet - and put the stage's blurb on the first tile
of each group (
intro). With only one group the overview leaves the heading out entirely (§3). - Within a group, sort tiles alphabetically (case-insensitive) by
header, then bysub. Sorting byheaderfirst keeps numbered series together and in order (Binding I,Binding II,Binding III, … underneath each other; likewisePopover I…IV,Popup I…III). The group order from rule 4 is untouched; only the tiles inside each group are ordered. - Deleting a sample drops its tile, and nothing else moves — the groups come from the learning path (rule 3), not from the tree, so a category loses its heading only when its last sample goes.
- After every change, verify:
get_catalog( )and the tree agree — same apps, same grouping, none missing. The safest way to regenerate is to rebuild the catalog straight from the physical tree (one tile per class) and carry over the existingheader/submetadata.
Keep the VALUE #( ... ) literal one tile per line, aligned as in the existing
catalog. Follow all ABAP rules in §7 (backticks, 2-space indent, LF, final
newline). Run abaplint — 0 issues — before committing.
Adding a sample
- Create the class in
src/— §2 says what qualifies, and there is no other folder (§1). - Regenerate the overview catalog and
SAMPLES.md:npm run launchpad(§4). abaplint→ 0 issues → commit (English message).
Removing or renaming a sample
- Delete or rename the two files (
FOLDER_LOGIC=PREFIX— the file name is the class name, and there is no folder to move between, §1). - Regenerate the overview catalog and
SAMPLES.md:npm run launchpad(§4). - Check the tree still holds to §1:
npm run check:agentsrefuses a folder undersrc/, andnpm run check:orphansa sample class no catalogue reaches — a class in a subfolder, or one without its.clas.xml. Rule 2 of §4 says every sample is listed; this is what enforces it from the tree side. abaplint→ 0 issues → commit.
Before every commit
npm run checknpm run check is the whole of CI, minus the one step that cannot be run
on a tree you want to keep (below). Every workflow that can make a pull request
red has a step here, and every step here has a workflow — so a green run
locally means a green run there, which is the only reason to run it at all.
It used to be six of eleven, and the three it was missing were the three
nobody thought to run by hand.
In the order they fail fastest:
| step | workflow | what it holds |
|---|---|---|
npm run check:pin |
check-framework-pin |
every abaplint config resolves abap2UI5 from the same, explicitly named branch — no config quietly lints against a different framework than its neighbours |
npm run lint |
abap-standard |
abaplint reports 0 issues (abaplint.jsonc, v750) |
npm run check:cloud |
abap-cloud |
the same tree against the ABAP Cloud API — main is installed there as it is (§2) |
npm run check:abap2ui5 |
check-abap2UI5 |
the abap2UI5-linter: the app class and the view it builds, plus a headless render of every view. New findings fail; abap2ui5lint-baseline.json holds the debt frozen at adoption, and an entry whose finding is gone fails too |
npm run check:agents |
check-docs |
no drift between the §1 layout and the tree: one flat package, no subfolders, the documented CTEXT |
npm run check:orphans |
check-docs |
every z2ui5_cl_smp_app_* class sits where a catalogue reads it (§1) |
npm run check:keywords |
check-keywords |
every sample carries @keywords and @summary, first line, lowercase (§4) |
npm run check:api-keywords |
check-api-keywords |
every framework cs_event-* constant a sample passes, and every call of a curated client method (popup_display, popover_display, nest_view_display, nav_app_call, the hash and app-state calls, …), stands in its @keywords (§4) — the script's header says what is left out and why |
npm run check:markers |
check-docs |
every (A) / (C) / (A,C) on a DESCRIPT is backed by the code, and every frontend action or custom control is marked (§12) |
npm run check:titles |
check-docs |
every sample's page title is abap2UI5 - + its DESCRIPT without the marker (§12) |
npm run check:launchpad |
check-docs |
the overview catalog and SAMPLES.md still mirror the folder tree (§3, §4) |
npm run check:catalogue |
check-docs |
the committed catalogue.json still mirrors the folder tree, and keeps the shape its consumers parse (§3) |
npm run check:derived |
check-docs |
the committed catalogue-derived.json — the linter's half of the catalogue — still matches what the linter derives from the tree ("The catalogue", below) |
npm run check:atc |
check-atc |
four extended-check (SLIN/ATC) findings abaplint does not model: a SELECT without WHERE and without "#EC CI_NOWHERE, sy-subrc after a dynamic ASSIGN, a text symbol passed to a parameter, an ABAP Doc @raising the method's RAISING clause does not declare |
npm run check:patterns |
check-app-patterns |
three app-code shapes that build, lint and run and are still wrong: a sibling chained after a statement's head element (§10, one statement per sibling; a leading x->end( ) is fine), nav_app_leave( ) handed get_app( …id_prev_app_stack ) directly or through a variable (§9), and an Input bound untyped to a numeric attribute the class computes with, in a class that never reads get( )-t_model_skipped |
npm run check:selftest |
check-selftest |
check:atc, check:patterns and check:api-keywords against fixtures (scripts/test/): every rule fires on its shape and stays silent on its look-alikes — a rule that stopped matching would otherwise read as a clean tree |
npm run check:prose |
check-docs |
every class name written in prose exists, here and in the sibling repositories |
npm run check:docs-links |
check-docs-links |
every " @docs URL resolves, and its page names the class back (§4) |
npm run check:app-rules |
check-app-rules |
the abaplint rule block still matches its source in abap2UI5 (§6) |
npm run rename |
check-rename |
the samples still rename out of the z2ui5 namespace; writes to the gitignored output/, never to src/ |
npm run e2e (not in check) |
e2e |
every sample boots in a headless browser on the transpiled backend and survives its first input, its first row and six button presses: no fatal overlay, no page or console error, no backend 4xx/5xx - E2E.md |
check:launchpad, check:catalogue and check:derived run the generators
with --check: same render, compared instead of written (one tail for all of
them, scripts/lib/emit.mjs). The generators are the source of truth either
way, because a check that regenerated differently from the generator would be
worse than none. The catalogues job of check-docs.yaml is where the three
run, on every pull request and on main; nothing in CI regenerates them (§4).
The last three talk to the network — check:app-rules and check:docs-links
prefer a sibling checkout and otherwise fetch, and both say so and pass when
they can reach neither: a gate must not go red because github.com is (§6). That
degradation is why check:app-rules is in the aggregate now; it was left out
back when an unreachable source was a failure.
The one CI step that is not here: npm run downport (abap-702,
publish-702). It is not a check, it is the 702 build: it runs
abaplint --fix over the whole tree, so running it leaves you with a
downported working copy rather than an answer. Run it deliberately, on a
clean tree, and git checkout . afterwards.
Nor is npm run e2e (e2e, on pull requests that touch src/ or the
harness). It needs npm run e2e:setup (abap2UI5 at A2UI5_PIN, cloned into
the git-ignored .abap2UI5) and npm run e2e:build first, about twelve
minutes in all. It is the only gate that RUNS a sample: every other step
reads the source or a reconstructed view, and the first run (2026-10-09) found
four defects in samples that had passed all of them - a view the XML parser
refused, a binding to a PROTECTED attribute that answered HTTP 500, an icon
drawn before its font was registered, a nested template UI5 called a future
fatal error. What it
expects to fail is e2e/expected.mjs, each entry with its reason; E2E.md
says how to run one sample and why the harness looks the way it does.
By hand, because no script covers it:
- abapGit file format for all file types: UTF-8, LF only, final newline, 2-space indent (§6).
- Run
abaplintbefore every commit. It must report 0 issues. - Configuration:
abaplint.jsonc - Install:
npm install -g @abaplint/cli - Run:
abaplint - The rule block below the marker is a CHECKED COPY of the shared app rule
set, and its source is
abap2UI5/abap2UI5
.github/abaplint/app-rules.json— the repository where the rest of "how to write an abap2UI5 app" already lives (thebuild-an-appandview-chain-layoutskills,docs/agents/building-apps.md,abap-check,ui5-check), because a shared thing needs one owner. Change it THERE first, then copy it here; this repository, samples-controls and samples-stack are consumers of that file, not peers of each other.- This replaced a three-way peer comparison, deliberately: three peers have
no answer to which of them is right, a repository without its own copy of
the checker turned the other repositories' CI red when it drifted, and
the peer checker compared rule NAMES only — so switching a rule to
falseto get a pull request through, precisely the drift it existed to catch, read to it as no change at all. - The gate is
scripts/check-app-rules.mjs(npm run check:app-rules, and thecheck-app-rulesworkflow on every pull request and push tomain). It compares PARSED SETTINGS against the source, preferring anabap2UI5checkout next to this one and falling back toraw.githubusercontent.com. It is the one gate here that needs the network: when the source is unreachable it says so and passes, rather than going red because github.com is. abap2UI5 checks the same thing from its side (shared-file-gate.mjs) — that is the source noticing, this is the consumer noticing. - abaplint has no
extends, so there is no shared file to include — the checked copy is the mechanism, and the block carries a header saying so. - Only
global,dependenciesandsyntaxare per repository (release floor, dependency set, suppressions) — plus exactly one rule:object_naming, which encodes the repository's token (SMP / SMPC / SMPS) and is the only rulecheck-app-rulesexcludes from the comparison. It sits last in the file behind a marker that says so. Everything above that marker must match the source.
- This replaced a three-way peer comparison, deliberately: three peers have
no answer to which of them is right, a repository without its own copy of
the checker turned the other repositories' CI red when it drifted, and
the peer checker compared rule NAMES only — so switching a rule to
- Every rule abaplint ships is listed in the config — all 212 of them
(2026-08-16; it was 17 here, 44 in samples-controls and 41 in
samples-stack, the rest defaulting to off unnoticed; 212 since abaplint
2.120.75). 190 are on. A rule
is never left out of the file. When an abaplint upgrade adds one, add the
key to
app-rules.jsonin abap2UI5 and copy the block into all three consumers: on if all three corpora pass, off with the reason in a comment above it if they do not. An unlisted rule reads as "nobody decided" rather than "decided against". - The 22 that are off carry their reason in the file. In short: four rules
want Hungarian notation and
no_public_attributeswants the model hidden, both against §7 and §9;abapdoctreats demos as a published API; seven rules read a view builder chain or aVALUE #( )data table as a malformed parameter list, and that layout has its own gate (chain-house-layoutinnpm run check:abap2ui5, §10);prefer_inline/no_inline_in_optional_branchesmove declarations the samples place deliberately, andprefer_inline_castfolds the previous app a sample reads back into one chained cast;prefer_correspondingproposes a rewrite that does not activate on a generic field symbol;smim_consistencycannot resolve a MIME folder that lives on the system;prefer_string_templateandprefer_insert_into_tablewould be style rewrites of 1,811 and 92 statements across the three corpora;no_dynamic_stuffflags the dynamic calls some samples exist to show; andgeneric_regexhas no pattern to check. - Several rules run with flags off or an
excluderather than wholesale. The ones worth knowing here:check_subrc(selectSingle,selectTable— "no rows" is a legitimate state, and the SELECT either feeds a binding or is read back withOPTIONAL),dangerous_statement(dynamicSQL— it was the subject of the generic table browser samples in the testing package, gone since 2026-09-22 (§2) — the flag stays off, see the comment on it),double_space(keywordsandendParen— both would strip deliberate column alignment),no_yoda_conditions(onlyConstants— unrestricted it demandslines( t ) < iinstead ofi > lines( t )) andempty_structure(when— an event that only needs the round-trip is a legitimate empty branch, with a comment where the code would be).- An
excludethat names another repository's files is not noise here: it is what lets one block serve three corpora.z2ui5_cl_smps_bp_*matches nothing under thissrc/, and removing it would break samples-stack on the next copy.
- An
- Write the flag set out in full when configuring a rule. abaplint
replaces the whole options object, so a partial one silently turns every
flag it omits off —
"check_subrc": { "selectTable": false }disables the rule entirely instead of narrowing it.
-
It is not a view checker. It validates a whole app class — the ABAP and the view it produces, together. Assuming it only inspects XML is the common mistake, and it misses the point: the group that catches what no other tool can is precisely the one that spans both sides.
Rule group What it catches metadatacontrols and members resolved against the UI5 metadata snapshot structuredefects in the shape of the document itself versioncontrols, members and enum values newer than the target UI5 release datathe view renders, but not with the data — or not for the user — the author meant abap2ui5defects living in the relationship between the ABAP class and the view it builds; silent at runtime, invisible to any UI5 tooling -
Configuration:
abap2ui5lint.jsonc(UI5 floor1.71, distributionopenui5,failOn: warning, baseline, badges) -
Run:
npm run check:abap2ui5 -
CI:
abap2UI5— as opposed toabap-standard/abap-cloud/abap-702, which lint ABAP itself against three target releases -
The gate is effective: every app class, every reconstructed view, and an
abap2ui5lint-baseline.jsonthat froze the adoption-time debt (#753) until every entry was fixed — empty since 0.6.1, kept so the next adoption has its shape. It was not always: while the linter still looked for the view builder's former name it found no checkable file at all, and a greencheck-abap2UI5badge then meant "nothing was checkable", not "the apps are clean". -
That is why a run reports what it LOOKED at, not only what it found. The gates log every file into a collapsed group while they run, and the run closes with a summary — classes, views reconstructed (and how many classes produced none), controls, bindings and icons judged, the control histogram, what the baseline swallowed and per rule, the phase times:
sources <n> app classes (<n> building a view) views <n> documents reconstructed, nested <n> deep, <n> class produced none judged <n> controls of <n> types, <n> bindings, <n> icons, <n> attributes gates properties <n> files, render <n> documents(The numbers are the run's, not this file's: the two README badges below carry the last ones, and the job summary of every
check-abap2UI5run prints them.)(No
baselinedline any more:abap2ui5lint-baseline.jsonhas been empty since 0.6.1 — the one frozen finding was fixed rather than carried.)A
judgedline of zeroes, or aproduced nonecount that is the whole corpus, is the earlier failure repeating itself — and now it says so instead of printing "Success! No findings detected."Since 2026-09-22 the count is ZERO, and the line is absent from the summary altogether. Every class in this repository produces at least one reconstructed view. That is the state to hold: a
classes produced noneline reappearing in a run is a sample that lost its view, which is the failure the count exists to catch — look at the named class before accepting it.Since linter 0.8.0 the
sourcesline counts two classes more and says why:(<n> building a view, 2 building none here - the view comes from another class). Those two arez2ui5_cl_smp_app_105andz2ui5_cl_smp_app_112, the sub-apps of theNested Viewsamplez2ui5_cl_smp_app_104(the accepted exception below): they build into the view reference 104 hands them and display nothing themselves. That is the only acceptable content of that bracket; a third class in it is a sample that lost its view.The shape that used to produce none was the "main app calling subapps" scaffold: the class builds a page, keeps the handle in an instance attribute, creates the sub-app with
CREATE OBJECT mo_app TYPE (class)and hands the handle over throughCALL METHOD mo_app->(`SET_APP_DATA`); the sub-app builds into it and a dynamicASSIGN mo_app->(`MV_VIEW_DISPLAY`)decides when to display. The linter resolves each builder statement against the handle it is written on, so a handle that leaves the class through a dynamic call is unfollowable — by design, not by oversight. There were eight classes of that shape: seven in the testing package (117,131,185,191,195,211,338, measured 2026-09-04) and the500aof the binding-error series, which had reached the catalogue shortly before. All eight are gone (§2) — what each of them asserted is a unit test in abap2UI5 now, the last one's inz2ui5_cl_ui5_srv_model'sltcl_07_view_host. Do not write another one here. A view that only exists once a second class has been called by name is a view no gate in this repository can judge. The one accepted exception isz2ui5_cl_smp_app_104, theNested Viewsample that embeds another app's view: it instantiates the sub-app over RTTI (CREATE OBJECT app_sub TYPE (classname)) and hands it the container through a dynamicASSIGN app_sub->(VIEW_PARENT), because embedding a class named at runtime is what it demonstrates. Its own master view is judged like any other; the embedded one is not, and the sample says so. -
The two README badges (
.github/badges/abap2ui5.jsonand.github/badges/check-abap2ui5.json, shields.io endpoint files) carry the same statement, split along what they mean: abap2UI5 | n apps · n views · n controls is what is here, blue, a fact; check-abap2UI5 | n rules passed is what the gate made of it, green (or n problems, n errors, red). A run that finds nothing checkable turns both grey and says so. Every run rewrites them locally, and they are not committed (.gitignore):check-abap2UI5publishes them from main to thebadgesbranch, which the README reads, so the counts are what the last run on main actually checked. A sample added or removed moves them with the first run after its merge — nothing to commit, and no bot commit on the pull request.
Every script is an ES module and is named .mjs. No CommonJS, no
require( ), no __dirname — resolve the repository root from
fileURLToPath(import.meta.url), the way every script here already does.
The repository ran two module systems side by side until 2026-08-18: five
CommonJS .js files and three ESM .mjs ones, with no rule saying which a new
script should be. That is not a style preference. A .js file cannot import
the .mjs scan, so a check written the ESM way could not reuse
lib/scan-samples, and one written the CommonJS way could not await a
fetch( ) at the top level — which is exactly what the two network-aware gates
do. The split decided what a new check was allowed to reuse, silently, by the
extension somebody picked. Both sibling repositories are ESM throughout;
so is this one now.
Everything else about a script follows from that:
- No dependencies. Plain node, so a gate is a few seconds and needs no
npm ci—check-docs,check-keywords,check-api-keywords,check-docs-links,check-atc,check-app-patterns,check-selftest,check-framework-pinandcheck-app-rulesrun theirnpm run check:*script without an install. package.json is the one spelling of every gate: a workflow calls the npm script, nevernode scripts/x.mjsornpx <tool>on its own, so what CI runs and whatnpm run checkruns cannot diverge. The one step that calls the linter directly is the markdown job summary incheck-abap2UI5.yaml, and the comment beside it says why (its flags make it a report, not the gate). - One scan, two renderers. Anything that reads the sample tree goes through
scripts/lib/scan-samples.mjs(§4). A second scan drifts silently. - A scan that cannot place a class says so.
scanSamples( )returnsorphansnext toareasandhidden, andcheck-orphan-samples.mjsrefuses them (§1). The two skips that produce one — a class in thesrc/root, a class in a top-level package that is not an area — were barecontinues until 2026-09-14, which is how fourteen samples went missing from both catalogues at once. Never add a silentcontinueto that loop: a class the scan drops has to come back out of it somewhere. - A gate that needs the network says so and passes when it cannot reach it
(
check-app-rules,check-docs-links) — see §6 below and the header ofscripts/check-app-rules.mjs. Prefer a sibling checkout over a fetch, so a developer with the whole ecosystem cloned is checked offline.
All serialized files (.abap, .xml, and any other abapGit-managed file types)
must conform to the abapGit file format:
- Encoding: UTF-8 (with optional BOM:
xEF BB BF) - Line endings: LF (
x0A) only — never CRLF - abapGit
*.clas.xmlsidecars start with the UTF-8 BOM (EF BB BFbefore<?xml) — abapGit writes them that way, and a BOM-less sidecar produces a spurious diff on the next push from a system (human fixes 2026-07-18). Copy an existing sidecar as template. - Final newline: every file must end with a single newline character after the last line
- Indentation: 2 spaces — never tabs
- Line length: max 255 characters per
.abapsource line (hard ABAP limit — longer lines break the abapGit import with "Literals across more than one line are not allowed"; enforced via the abaplintline_lengthrule). Split long string literals into&&chunks.
Always verify consistency for all file types before committing, not just
.abap files. abaplint covers .abap files; for .xml and other files, check
manually or via editor tooling that the above rules are met.
This repository ships CLAS and DEVC. Never add a TABL, DTEL, DOMA,
DDLS, BDEF or any other dictionary object, and never make a sample depend
on one it would have to bring along. A sample a reader can run is a sample that
is one class: they pull the repository, start the class, and it works. A
dictionary object turns that into an activation order, a transport and a
SELECT against a table nobody filled.
abap2UI5 holds the same rule for itself (No new dictionary objects in its
AGENTS.md) and acted on it: the released structure z2ui5_t_02, added
purely so a sample could point a dynamic type at something, was removed on
2026-09-22 — nothing here ever named it.
Where a sample genuinely needs a type name computed at runtime
(CREATE DATA … TYPE STANDARD TABLE OF (name)), it names a table that is
already on every system the sample runs on. Today that is
Z2UI5_CL_SMP_APP_061, which names Z2UI5_T_01 — abap2UI5's own draft table,
borrowed as a name that exists, not used as an API: the sample only reads its
shape, never its rows, and if the framework ever changes the table the sample
changes the string. Say that in the sample, as 061 does. Data a sample needs
for its own sake is built in ABAP — VALUE #( ( … ) ( … ) ) in model_init( ) —
never selected from the dictionary.
- Follow the SAP ABAP Style Guide.
- Never use an init flag attribute (
check_initialized,mv_init,is_initialized, etc.). Always useclient->check_on_init( )instead. - An
abap_boolis compared toabap_true/abap_false— never asked withIS INITIAL/IS NOT INITIAL, which is the question for a string that might be empty (IF mv_flag = abap_false.,DELETE lt_x WHERE flag = abap_false.). The threecheck_on_*( )methods returnabap_boolas well, and there the corpus writes the predicative call itself:IF client->check_on_init( ).,ELSEIF client->check_on_event( `LOCK` ).. NeverIF client->check_on_init( ) OR client->check_on_navigated( ).— thatORis redundant, see the lifecycle section below. Only a NEGATIVE branch is spelled out, as= abap_false— there is no negated predicative form here. The rule and its reasons live in abap2UI5'sbuild-an-appskill. - Use backticks for all string literals, not single quotes.
- Use string templates (
|...|with{ }for embedded expressions) instead of&&for string concatenation (e.g.|item { name }|not`item ` && name). - Prefer functional to procedural language constructs — use
var = VALUE #( ).to reset a variable, neverCLEAR var.. - Use type prefixes only for tables and structures: prefix table variables/attributes with
t_(e.g.t_items) and structure variables/attributes withs_(e.g.s_screen). Do not add prefixes to scalar variables or object references. - Name local types with a
ty_s_prefix for structure types (e.g.ty_s_row) andty_t_for table types (e.g.ty_t_rows). Only define aty_t_table type when it is used more than once — for a single-use table, declare it inline withSTANDARD TABLE OF ty_s_xxx. - No blank line between a
TYPESdefinition and theDATAdeclaration that directly uses it. - Class names are always written in lowercase in both
DEFINITIONandIMPLEMENTATION— never uppercase. - Classes are not
FINAL— do not add theFINALkeyword to class definitions. - Use
DEFINITION PUBLIC.— neverDEFINITION PUBLIC CREATE PUBLIC.(CREATE PUBLICis the default and adds unnecessary overhead). - Always include
PROTECTED SECTION.andPRIVATE SECTION.in the class definition, even if empty. - Keep
PRIVATE SECTION.always empty — declare everything atPROTECTED SECTION.level at most. - In every section (
PUBLIC SECTION.,PROTECTED SECTION.), always follow this declaration order:TYPESfirst, thenDATA, thenMETHODS. - Blank lines — class definition (
EMPTY_LINES_IN_CLASS_DEFINITION):- Add one blank line above each section keyword (
PUBLIC SECTION.,PROTECTED SECTION.,PRIVATE SECTION.) — unless the preceding section is empty. - No blank line directly below a section keyword.
- No blank line above
ENDCLASS.. - Max 1 consecutive blank line inside the definition block.
- Add one blank line between groups of different declaration types (e.g. between
INTERFACESandDATA, orDATAandMETHODS).
- Add one blank line above each section keyword (
- Blank lines — outside methods (
EMPTY_LINES_OUTSIDE_METHODS):- Exactly 2 blank lines between
ENDCLASS.and the nextCLASS … IMPLEMENTATION.(i.e. between the definition and the implementation block). - Exactly 2 blank lines between two
METHOD … ENDMETHOD.blocks. - Exactly 2 blank lines between two top-level class blocks.
- Exactly 2 blank lines between
- Blank lines — inside methods (
EMPTY_LINES_WITHIN_METHODS):- Always add exactly 1 blank line at the very start of a method body (after
METHOD). - Always add exactly 1 blank line at the very end of a method body (before
ENDMETHOD). - Max 1 consecutive blank line inside a method body.
- Always add 1 blank line before an
IFblock — except when the method is a pure dispatcher (its only purpose is to jump to other methods, with no own logic before theIF). In that case, omit the blank line between the opening assignment and theIF. - Always add 1 blank line before
ELSEIFandELSE. - In setup methods (
model_initand similar), add 1 blank line between the last data assignment and the first non-assignment statement (e.g. before adata_read( )):METHOD model_init. price = `1234`. currency = `EUR`. data_read( ). ENDMETHOD.
- If a branch (
IF,ELSEIF,ELSE) contains more than one statement, add 1 blank line directly after the condition line as well:me->client = client. IF client->check_on_init( ). product = `products`. quantity = `500`. view_display( ). ELSEIF client->check_on_event( `SAVE` ). data_update( ). ENDIF.
- Always add exactly 1 blank line at the very start of a method body (after
- ABAP Doc (
"!) position — not caught byabaplint, but the extended check (SLIN/ATC) reports "ABAP Doc comment is in the wrong position": a"!block must sit directly before the one declaration it documents. Inside a chained statement (TYPES: BEGIN OF …) that means directly before the component, within the chain. It is never allowed inside aMETHODSparameter list — document parameters in the method's own doc block above theMETHODSkeyword via"! @parameter <name> | <text>. A plain"comment (no!) is fine anywhere. - ABAP Doc is parsed as HTML: escape a literal
<,>or&as<,>,&. - A mock table is a table. In a
VALUE #( )of three or more rows with the same field list, pad every cell to the width of its column and leave the LAST cell of a row unpadded, so no spaces pile up before the closing). Rows whose field lists differ have no column to align and stay as they are; a row that would break 255 characters once padded is wrapped at the same field boundaries in every row instead. - A call that fits on one line goes on one line (budget 120 characters) — stacking parameters is for calls that do not fit, not for calls that happen to have two. The view chain is the exception: it keeps one call per line (
view-chain-layout), and at_arglist wrapped over several lines stays wrapped, hanging under its first element. - Always run
abaplintafter every change. It must report 0 issues before committing. - Before starting app development, read all active rules in
abaplint.jsoncand follow them throughout. - The rules that most often bite when writing a new sample (all of them
enforced since 2026-08-16, see §6):
- A table type is
WITH EMPTY KEY, neverWITH DEFAULT KEY. - A local type name starts with
ty_(ty_s_/ty_t_, §7 above). CASEneeds twoWHENbranches. One event is anIF— which is what §9 asks for anyway;CASEstarts at four.- Every
SELECTcarries anORDER BY(ORDER BY PRIMARY KEYif the order itself does not matter), andSELECT SINGLEneeds the full key — without it, useORDER BY PRIMARY KEY ... UP TO 1 ROWSand read row 1. ASSIGNandREAD TABLEare followed by ansy-subrccheck. Reading an unassigned field symbol dumps; a missedREAD TABLEleaves the previous work area in place, which is worse than a dump because it looks like data.- An explicit
DATAbelongs at the top of its method (definitions_top). An inlineDATA( )at the point of use is fine and is not affected. - No commented-out code, no unused variable, type or method, no empty
WHEN, no end-of-line comment, no!before a parameter name. - Two blank lines between methods — three is a finding.
- A table type is
For deeper information about how the abap2UI5 framework works internally —
architecture, roundtrip processing, data binding engine, session persistence,
and core classes — refer to the
abap2UI5 repository and its AGENTS.md.
The mechanics — the main( ) roundtrip, the three check_on_*( ) flags, the
client API of z2ui5_if_client (views, popups, _bind( ), _event( ),
follow_up_action( ), navigation, the URL hash and the app state), messages
and popups — are the framework's to describe, and it does, in
docs/agents/building-apps.md
of abap2UI5 (the build-an-app skill), a guide the framework's own gates hold
to the interface. Read it before writing a sample, and do not copy it here: the
copy this file used to carry drifted from it in three places within a month.
What follows is only what this repository decides for itself.
Always chain the lifecycle checks with ELSEIF — never separate IF blocks —
in the order init, navigated, event:
IF client->check_on_init( ).
" what must happen ONCE - seed the model, seed a control-state flag
model_init( ).
view_display( ).
ELSEIF client->check_on_navigated( ).
view_display( ).
ELSEIF client->check_on_event( ).
on_event( ).
ENDIF.The init branch displays too. The chain runs exactly one branch per
roundtrip, and on the first one that is the init branch - the ELSEIF check_on_navigated( ) below it is skipped, so an init branch that only seeds
leaves the first start without a view.
check_on_init( ) true implies check_on_navigated( ) true (the guide
says why), so an init branch whose only statement is view_display( ) has an
ELSEIF twin doing exactly the same thing (the linter's
redundant-init-display), and
IF check_on_init( ) OR check_on_navigated( ). says the same redundancy in one
line. An app with nothing to seed drops the init branch entirely and dispatches
on check_on_navigated( ) and check_on_event( ) alone.
view_display( ) in the check_on_navigated( ) branch is always safe, and
always there. A called sub-app that took the screen leaves its own view
standing when it returns via nav_app_leave( ); the attributes survived the
roundtrip, so nothing is re-read — the view is re-displayed, and data_read( )
is not called there. After a popup the same call simply re-renders the same
view. The linter's missing-on-navigated-branch holds every class to it (§6),
and the two shapes it exempts are the ones that never own the main view slot:
a sub-app that renders into its parent's view (z2ui5_cl_smp_app_105 and
_112, where check_on_init( ) is the only place the view is built) and an
app that owns a popup instead of a view (z2ui5_cl_smp_app_501, excluded
by name in abap2ui5lint.jsonc with the reason beside it).
check_on_event( ) takes an optional event name. Check the event inline in the
ELSEIF chain when there are 2–3 events and no dispatch logic:
IF client->check_on_init( ).
...
ELSEIF client->check_on_event( `SAVE` ).
data_update( ).
ELSEIF client->check_on_event( `DELETE` ).
data_delete( ).
ENDIF.A CASE client->get_event( ) (inside ELSEIF client->check_on_event( )) starts
at 4 events, or when a dedicated on_event method is extracted (§11). The
framework guide dispatches with CASE from the first event; here the abaplint
rule that wants two WHEN branches decides (§7).
-
The back button is wired in the view:
press = client->_event_nav_app_leave( )on thePage'snavButtonPress, withshowNavButtonbound toclient->check_app_prev_stack( )(the §10 example) — no roundtrip. HandleBACKinon_eventonly when something has to happen with the app or the previous app instance before leaving:WHEN `BACK`. CAST z2ui5_cl_app_parent( client->get_app_prev( ) )->set_result( s_result ). client->nav_app_leave( ).
-
One browser step back is
client->follow_up_action( client->cs_event-hash_back ); back to the previous app isnav_app_leave( ).follow_up_action( )runs no raw JavaScript any more — avalthat is not acs_event-*name is not executed — sohistory.back()is not an option.z2ui5_cl_smp_app_499shows the wholehash_*family. -
Back to the caller is the bare
nav_app_leave( )— ornav_app_leave( event = … )to hand it an event. Never load the caller by id first (nav_app_leave( client->get_app( client->get( )-s_draft-id_prev_app_stack ) ), directly or through a variable): the bare call goes to the same app, and unlikeget_app( )it survives a caller whose draft has expired.npm run check:patterns(nav_leave_get_app) refuses it.
Views are XML strings passed to client->view_display( ), built with
z2ui5_cl_ui5_view_builder — the released builder in the framework's src/02.
It is generic: seven public methods build any UI5 view 1:1 — factory( ),
ele( ), tag( ), a( ), end( ), stringify( ) and the static
escape_literal( ) — so there is no list of supported controls and nothing to
wait for when UI5 adds one. Element and property names come straight from the
UI5 API Reference and are written exactly as
documented there. What each verb does, and the whole of the builder's
semantics, is section 3 of the framework guide (§9); three of its rules are
repeated here because samples get them wrong:
-
a( )takes exactly one ofv,b,t.vis the form for a binding, an event, a{/path}template and constant text;btakes an ABAP boolean and renderstrue/falseitself (a( n = `editable` b = mv_edit_mode ), never a conversion of your own);ttakes text that carries data — user input, a value read from a table — and escapes it as a literal, because a{in avis parsed as a binding. Where one attribute mixes text with a binding, escape the text part withz2ui5_cl_ui5_view_builder=>escape_literal( )insidev. -
Empty attributes are rendered. The builder writes every attribute you add, including an empty one — and
type=""orcolor=""is not a valid UI5 enum value. An attribute whose value may be empty at runtime therefore goes under anIF, it is not simply passed:DATA(button) = toolbar->tag( `Button` )->a( n = `text` v = name ). IF icon IS NOT INITIAL. button->a( n = `icon` v = icon ). ENDIF.
-
There is no raw-text node, so an inline
<style>body or any other raw markup goes into thecontentattribute of acore:HTMLleaf. Write the decoded markup — the builder escapes it on stringify:page->tag( n = `HTML` ns = `core` )->a( n = `content` v = `<style>` && css && `</style>` ).
And there is no way back up to a named ancestor:
end( )climbs exactly one level, so a view is built the way it nests. When a helper method needs a container the caller owns, the caller passes that reference — see thenest_view_display( )samples of theNested Viewcategory, which are handed the container they render into rather than searching for it.
Always add 1 blank line before DATA(view) = z2ui5_cl_ui5_view_builder=>factory( ).
to visually separate view construction from preceding logic.
Always build the view in view_display and call
client->view_display( view->stringify( ) ) as a standalone statement at the
end — never nested inside the chain.
The chain is the only picture of the view's tree there is, so its layout is
load-bearing rather than cosmetic. Six rules, and they are identical in
abap2UI5/samples-controls — the two corpora were unified in one pass after
a survey found them following opposite conventions:
- One call per line. Every
ele( ),tag( ),a( )andend( )opens its own line with)->. A control never shares its line with the container it opens, nor with its own attributes. - Four spaces per level, everywhere. A child sits one level in from its container, a control's attributes one level in from the control. The same step throughout every file — a chain that steps by 2 and then by 4 and then stops moving is no longer describing the tree, it is decorating it.
- The closing paren rides with the arrow. Never a
)alone at a line end; carry it to the next segment so it always reads)->. end( )stands alone in the column of theele( )it closes. That is what makes an ascent over several levels visible instead of hidden. What is forbidden is the run on one line —)->end( )->end( )->ele( `footer` )->ele( `OverflowToolbar`changes four levels where nobody can see them.- Align the
v =/b =column within one control's attribute block. stringify( )is a standalone final statement — never nested in the chain.
METHOD view_display.
DATA(view) = z2ui5_cl_ui5_view_builder=>factory(
)->ele( n = `View` ns = `mvc`
)->a( n = `displayBlock` v = `true`
)->a( n = `height` v = `100%`
)->a( n = `xmlns` v = `sap.m`
)->a( n = `xmlns:mvc` v = `sap.ui.core.mvc`
)->a( n = `xmlns:form` v = `sap.ui.layout.form` ).
view->ele( `Shell`
)->ele( `Page`
)->a( n = `title` v = `My App`
)->a( n = `showNavButton` b = client->check_app_prev_stack( )
)->a( n = `navButtonPress` v = client->_event_nav_app_leave( )
)->ele( n = `SimpleForm` ns = `form`
)->a( n = `title` v = `Form Title`
)->a( n = `editable` b = abap_true
)->ele( n = `content` ns = `form`
)->tag( `Label`
)->a( n = `text` v = `Quantity`
)->tag( `Input`
)->a( n = `value` v = client->_bind( quantity )
)->tag( `Button`
)->a( n = `text` v = `Post`
)->a( n = `press` v = client->_event( `POST` ) ).
client->view_display( view->stringify( ) ).
ENDMETHOD.The hierarchy is mvc:View → Shell → Page → form:SimpleForm →
form:content → leaves, and every one of those levels is four spaces. Label,
Input and Button are siblings inside content, so they are added with
tag( ) and stay at the same indent while their attributes step in.
Both shapes are correct, and the choice is about the view, not about style:
- One chain — the whole view in a single statement, ascending with
end( ). The shapesamples-controlsuses throughout, because a 1:1 port mirrors one original XML file. - One statement per subtree — hold a container in a variable
(
DATA(page),DATA(cont),DATA(lo_columns)) and start a new statement from it. The shape most of this corpus uses, and the better one when a subtree is filled from a loop, when the same node is filled twice, or when a teaching sample reads better with the parts named.z2ui5_cl_smp_app_052is the worked example.
The split shape reconstructs and renders fine — the linter reads every
document in this corpus from it. What is not allowed is mixing them inside
one subtree, and blank lines inside a chain: they belong to the long
single-chain shape, where they separate an ele( ) block from its first child.
The rules above are also the view-chain-layout skill
(.claude/skills/view-chain-layout/), kept byte-identical in abap2UI5 and
abap2UI5/samples-controls — read it before writing or reformatting a chain.
The linter's chain-house-layout rule (part of npm run check:abap2ui5,
in check-abap2UI5.yaml) checks all six rules and npm run fmt:chains
applies them. The fixer rewrites whitespace between chain segments only,
and the layout survives because every fix is verified against the rule — a
formatting change can never alter what the view builds.
What the layout rule cannot see is a sibling chained after the head
element of a split-shape statement: page->tag( A )->…->tag( B ) builds
two siblings, and the rule indents B one level deeper than the tree has it.
npm run check:patterns (chain_sibling) refuses it — start a new statement
per sibling from the container. A statement that opens with x->end( ) to
reach the parent of a held container is fine.
Binding paths always come from a bind call — never hardcode them. Every
model value a view references must be registered through
client->_bind( ): a
hand-written path ({/START_DATE}, or { path: '/START_DATE', ... } in a
raw binding-info string) is NOT part of the serialized model — the frontend
receives no data for it and typed/object properties crash on the missing
value (human find 2026-07-18 in Z2UI5_CL_SMP_APP_456/_457). Compose raw
binding-info strings with the bare path from
client->_bind_path( x ).
Always _bind( ), never _bind_edit( ). Both bind into the same root
model — the split between them disappeared with the XX/ view-model node — so
_bind_edit is only an obsolete alias and is slated for removal.
The single exception is a mapping that differs per direction, because _bind
has no custom_mapper_back / custom_filter_back parameters; no sample in
this repository currently needs that — one that does must say so in a comment
at the call.
Call it "binding", never "one-way"/"two-way" binding — in sample titles,
message strips, comments and @keywords alike. With only _bind( ) left, and
the value always written back before the event handler runs, the qualifier
distinguishes nothing and makes readers look for a second mode that does not
exist. Say "bound attribute", "the value is written back before the event
handler runs".
"One-way" is correct only for a real UI5 one-way model that is not _bind( )
— the device> JSONModel in z2ui5_cl_smp_app_445, for example.
The former standalone XML builder
z2ui5_cl_util_xmlis no part of the framework any more: it left abap2UI5 with the otherz2ui5_cl_util*classes on 2026-11-02 and ships in abap2UI5-obsolet. No sample uses it, and a sample must not depend on it — do not use it in new samples.
The
z2ui5_cl_pop_*helper popups are obsolete. They live in the framework's obsolete package (src/99) and must not be used any more: never reference one from a sample, and never create a sample demonstrating one (human decision 2026-08-12; the last two usages —z2ui5_cl_pop_to_confirminZ2UI5_CL_SMP_APP_279,z2ui5_cl_pop_image_editorinZ2UI5_CL_SMP_APP_306— were removed the same day). A sample that needs a dialog builds it itself withz2ui5_cl_ui5_view_builder=>factory( )with acore:FragmentDefinitionroot +client->popup_display( ).
In VALUE #( ) constructor expressions with named fields, use either entirely inline (all fields on one line) or each field on its own line — never mix both styles in the same expression:
" Wrong — mixed
t_products = VALUE #(
( name = `Notebook Basic 15` product_id = `HT-1000` supplier_name = `Very Best Screens`
dimensions = `30 x 18 x 3 cm` weight_measure = `4.2` weight_unit = `KG` ) ).
" Correct — one field per line, = signs aligned
t_products = VALUE #(
( name = `Notebook Basic 15`
product_id = `HT-1000`
supplier_name = `Very Best Screens`
dimensions = `30 x 18 x 3 cm`
weight_measure = `4.2`
weight_unit = `KG` ) ).A later row names every component an earlier row set, with an empty
value ( ``, 0, `abap_false`, `VALUE #( )`) where it has none - an empty
row `( )` after a filled one included. On 7.40+ a left-out component is
initial; on the `702` branch, which is the abaplint downport, every row of a
`VALUE` is built in one work area that is never cleared, so the row inherits
the previous row's value - silently, nothing reports it. The upstream fix is
tracked in abap2UI5's backlog (`abaplint-downport-value-row-not-cleared`);
until it ships and is pinned, spell the components out. `FOR` rows and rows
that all assign the same components are not affected.
Write everything directly in main — no method encapsulation needed. Count only the lines inside the main method, not the total class length.
Do not extract view_display or any other helper method just because the app has a view. A separate view_display method is only justified when the app is large enough to warrant the full canonical structure (≥ 50 lines in main). Extracting it in a simple app adds unnecessary indirection.
When the logic no longer fits inside main, extract view_display, on_event and - where the app seeds data - model_init, under exactly these names. main then becomes a pure dispatcher. Only add further methods (data_read, etc.) when they are actually needed.
One order, in the declarations and in the implementation: main, view_display, on_event, the event handlers and helpers, and model_init last. A reader meets what the app shows first, then what it does, and the seed data - usually the longest and least interesting part - at the end. model_init only seeds: the check_on_init( ) branch of main calls it and then view_display( ). (Until 2026-11 the first extraction was called on_init and displayed the view itself; samples-controls always used model_init, and the three repositories read alike now. An on_init remains only where the init path does more than seed and display - apps 004, 081, 381, 382, 421, 501, 543.)
In the check_on_navigated( ) branch the dispatcher calls view_display( ) directly — the app state survived the serialization, only the view must be re-displayed. Extract a dedicated on_navigation method only when the app additionally needs to process results from the called sub-app (via get_app_prev( )) before re-displaying.
Never create a pass-through method with only one statement. If an extracted method (e.g. model_init) would contain only a single call, replace the method call in the dispatcher with that single call directly — and omit the pass-through method entirely. For example, if model_init would only call data_read( ), write data_read( ) directly in the IF client->check_on_init( ). branch instead.
When the body of a single WHEN branch in on_event grows too long, extract it into a dedicated method named on_event_<event> (e.g. on_event_save, on_event_delete). The on_event method then stays a thin dispatcher — one call per branch — and all the logic lives in the sub-method.
The following is the maximum structure. Only add methods that are actually needed.
CLASS z2ui5_cl_app_xxx DEFINITION PUBLIC.
PUBLIC SECTION.
INTERFACES z2ui5_if_app.
" bound data (DATA attributes for _bind)...
PROTECTED SECTION.
DATA client TYPE REF TO z2ui5_if_client.
METHODS view_display. " build and render the view
METHODS on_event. " user triggered an event
METHODS data_read. " SELECT from database
METHODS data_update. " INSERT / UPDATE / DELETE
METHODS model_init. " first call: seed what the app starts with
PRIVATE SECTION.
ENDCLASS.
CLASS z2ui5_cl_app_xxx IMPLEMENTATION.
METHOD z2ui5_if_app~main.
me->client = client.
IF client->check_on_init( ).
model_init( ).
view_display( ).
ELSEIF client->check_on_navigated( ).
view_display( ).
ELSEIF client->check_on_event( ).
on_event( ).
ENDIF.
ENDMETHOD.
METHOD view_display.
DATA(view) = z2ui5_cl_ui5_view_builder=>factory( ).
" ...
client->view_display( view->stringify( ) ).
ENDMETHOD.
METHOD on_event.
CASE client->get_event( ).
WHEN `SAVE`.
on_event_save( ).
WHEN `BACK`.
client->nav_app_leave( ).
ENDCASE.
ENDMETHOD.
METHOD on_event_save.
data_update( ).
ENDMETHOD.
METHOD data_read.
" SELECT ...
ENDMETHOD.
METHOD data_update.
" INSERT / UPDATE / DELETE ...
ENDMETHOD.
METHOD model_init.
" the values the app starts with ...
data_read( ).
ENDMETHOD.
ENDCLASS.Every non-obsolete part of z2ui5_if_client is demonstrated by a sample
somewhere in the three sample repositories. Measured 2026-09-22 against the
ABAP source of all three checkouts — this repository, samples-stack and
samples-controls — not against a catalogue and not against this src/
alone. The surfaces counted are the constants of cs_event, the methods of
the interface, the components of ty_s_event_control and the parameters of
_bind( ).
| Surface | Total | Without a sample anywhere |
|---|---|---|
cs_event-* |
34 | 0 |
z2ui5_if_client methods |
40 | 7 |
ty_s_event_control components |
5 | 0 |
_bind( ) parameters |
10 | 2 |
(Totals re-counted 2026-09-25 against the framework's z2ui5_if_client; the
coverage column is the 2026-09-22 measurement.)
All nine are obsolete, and that is the whole finding — there is no uncovered feature, only features nobody should be shown:
- the five
*_model_update( )methods do nothing (the framework pushes the model itself sincemain_endcompares before and after); _bind_edit( )is an alias of_bind( ),_event_client( )a superseded spelling offollow_up_action( );custom_mapper/custom_filterare marked obsolete at the declaration.
cs_event-z2ui5 stood in the table too, as the one constant without a
sample: the legacy escape hatch in the interface's own "obsolet" block.
abap2UI5 removed it on 2026-09-22 together with the z2ui5 frontend global
whose functions it called, which is what took the row to 34 / 0. A function an
app defines on window is not something a sample here demonstrates —
follow_up_action( ) runs no raw expression any more, and what an app needs
beyond the cs_event set is a custom control.
cs_event-image_editor_popup_close stood here too, as "belongs to a
z2ui5_cl_pop_* popup this repository may not demonstrate". That reading was
wrong and the audit is the reason it surfaced: the constant was not waiting on
the frozen package, it was waiting on a capability the framework did not have
— reading a value off a control in another view slot into an event argument.
abap2UI5 added $controller.slotValue( ) and removed the constant on
2026-09-22. A symbol that has no sample because nothing can express it is a
gap in the framework, not in this catalogue — worth saying which of the two
it is before filing it under "obsolete".
Do not write a sample for any of them. A demonstration is a promise that the thing is the way to do it.
Not counted, because no sample repository can carry them: the two methods of
z2ui5_if_ui5_exit (an exit is a class the installation writes — a sample
shipping one would take the exit over for everybody who pulls the repository)
and the ICF entry points of z2ui5_cl_ui5_http_handler (run,
factory_cloud, _http_get / _http_post, …), which a customer wires into a
handler class rather than an app.
This section was wrong twice in one day, the same way both times, and the rule is what came out of it:
- the first run grepped this
src/only and reportedplay_audioas demonstrated nowhere.Z2UI5_CL_SMPS_APP_487had been playing sounds insamples-stackthe whole time. A sample was written for it and withdrawn. - the second run fell back on the published
SAMPLES.mdof the other two — keywords and summaries, not code — and reportedpopover_closeas the one genuinely missing constant. It is insamples-controls, which simply does not put the constant in a keyword line.
A grep of one src/ answers "does this repository show it". The question
that decides whether a sample is worth writing is "does the ecosystem show
it", and only the source of all three answers that. Clone the other two
(git clone --depth 1) rather than reading their catalogues.
Re-run the audit when the framework's API snapshot changes, not on a
schedule: a new cs_event constant either gets a sample or gets a line above
saying why not, and that decision is the thing worth recording.
Learned while curating the sample catalogue — follow these so new/edited samples stay consistent:
-
Every sample opens with an intro
MessageStrip. As the first control in the page content (right after thePage, before the form or table), add a short, specific English explanation of what the sample demonstrates:page->tag( `MessageStrip` )->a( n = `text` v = `<one or two sentences: what this sample shows / does>` )->a( n = `type` v = `Information` )->a( n = `showIcon` b = abap_true )->a( n = `class` v = `sapUiSmallMargin` ).
Split a long
textinto`chunk ` &&continuation lines (≤255 chars/line, aligned under the first backtick). Hold the page in a variable for it (DATA(page) = view->ele(Shell)->ele(Page… ), the split shape of §10) rather than threading the strip into one long chain. -
DESCRIPTs of framework-action / custom-control samples carry a capability marker appended to the
<DESCRIPT>(leading space), surfaced in the overview:(C)— uses an abap2UI5 custom control (thez2ui5cc namespace:ele( n = … ns = `z2ui5` ),z2ui5.cc,xmlns:z2ui5).(A)— performs a frontend action. The list is closed — exactly these three, nothing "like" them:- a
client->follow_up_action( )call (including thecs_event-control_by_id/cs_event-control_global/cs_event-binding_callevents, which only ever travel through it); - a
client->_event_client( )call, the obsolete spelling of the same; - drag and drop — a control of the
sap.ui.core.dndnamespace (ns = `dnd`) or adragDropConfigaggregation. Any other client-side behaviour (an expression binding, a formatter, aliveChangewire, acore:require) is not(A); a new kind needs this list and the gate changed in the same commit. The ubiquitous back-buttonclient->_event_nav_app_leave( )does not count.
- a
(A,C)— both. Regenerate the overviews after changing any DESCRIPT (§4). An option on an ordinary roundtrip_event( )(s_ctrl, e.g.check_prevent_default) is not a frontend action: the event still goes to the backend and nothing else (Z2UI5_CL_SMP_APP_472carried(A)for it until 2026-10-08). The gate isnpm run check:markers(scripts/check-markers.mjs, thecapability_markersjob ofcheck-docs): it reads every tile's code with comments stripped and refuses a marker the code does not back as well as a missing one —(A)for exactly the three items above (the two calls looked for outside string literals),(C)for az2ui5-namespace element or anxmlns:z2ui5declaration. The two definitions live in that script and here; change them together. The legend a reader sees - under the overview app's list, in the preamble ofSAMPLES.md, asnaming.markersincatalogue.json- is written once, inscripts/lib/markers.mjs, and rendered by all three generators; change the wording there, never in a rendered copy.
-
A read-only info form disables its inputs (
a( n = `enabled` b = abap_false )) — do not leave display-only values in editable inputs (seez2ui5_cl_smp_app_122). -
No redundant footer Back button. The
Pagealready carries the nav-back button (showNavButton/navButtonPress, §9); do not add a secondBackbutton in the page footer (removed from the MessageBox / MessageToast samples). -
Must run on OpenUI5 1.71 — watch for "phantom control" 404s. An
ele( )that names an aggregation the parent does not have makes UI5 resolve it as a control class and 404 withfailed to load sap/<lib>/<name>.json 1.71, crashing the sample. Two real cases:ele( n = `heading` ns = `uxap` )under anObjectPageSection—sap.uxap.ObjectPageSectionhas noheadingaggregation. Put the section title ina( n = `title` v = … )and go straight tosubSections. (f:headingis valid under asap.fDynamicPageTitle.)footeron a popupDialog—sap.m.Dialogonly got a publicfooteraggregation ~1.110; aPage'sfooteris fine (sap.m.Page always had one). Every control/property here must exist since 1.71 (§2); when in doubt check "available since" in the demo kit.
-
sap.m.SimpleFormneedsa( n = `editable` b = abap_true )for its label/input pairs to line up on one row — without it the form renders in display mode and the first field is mislaid (fixed inZ2UI5_CL_SMP_APP_189; compareZ2UI5_CL_SMP_APP_133). -
StandardListItem:inforight-aligns to the far edge (a status/amount slot). For a secondary attribute that belongs with the title (e.g. a product's category) usedescription— a left-aligned subtitle — instead; the far-right float looks disconnected on wide screens (fixed inZ2UI5_CL_SMP_APP_454/_455). -
The page title carries the
<DESCRIPT>text, in the form`abap2UI5 - <DESCRIPT without the (A)/(C) marker>`— every sample follows it since 2026-08-13. A user clicks a tile in the overview (which shows the DESCRIPT) and the opened sample must name the same thing, so it is recognisably the right sample. Change the two together: renaming a DESCRIPT without the page title puts them out of sync again (they had drifted to "Focus II" and "Table Filters Reset after view Update"). The gate isnpm run check:titles(scripts/check-page-titles.mjs, thepage_titlesjob ofcheck-docs). It reads the firstPagebuilt after the main view'sShell— in the same chain, off a variable, or as the first page of a NavContainer in the Shell — and wants the title as that literal. Not judged: aDialogtitle, further NavContainer pages, nested-view pages, the overview app (abap2UI5 - Samples, §3) and the ZZZ helpers, which have no tile. -
Every main view opens
mvc:View→Shell→Page(the §10 example), neverView→Page, so all samples share the same outer frame (fixed inZ2UI5_CL_SMP_APP_143). -
Give a
SearchFieldan explicitplaceholder. Without one UI5 shows its locale default (German "Suchen" on a DE system), which clashes with the otherwise-English samples.
https://abap2ui5.github.io/browser-playground/samples/ — every sample of this
repository, of samples-controls and of samples-stack, searchable, for
somebody who has not installed anything yet. This repository used to publish
its own page for that (web/, on its own GitHub Pages); it was retired
2026-09-03 together with the two sibling pages. Three pages that each had to
explain that the other two existed were the reason for the shared family-nav
block, its three copies and the check policing them; one page needs none of it.
What this repository owes that page is data, and it owes it twice:
catalogue.json |
what the tree holds — class, folder, category, learning-path stage, title, @summary, @keywords, @docs (§3) |
catalogue-derived.json |
what the LINTER knows — minUi5, the needs that made it that release, and every control the sample BUILDS |
The second answers the question the first cannot: "which sample shows
sap.m.Table at all?" A category is what a sample is FILED under and
@keywords are what somebody thought to write down; neither is the list of
controls the view actually builds. scripts/generate-derived.mjs gets both out
of an @abap2UI5/linter pass — stats.types and the *-too-new findings,
which it computes anyway — and keys them by class so a consumer joins them
onto catalogue.json.
Two files rather than more columns, for the reason §3 gives for
catalogue.json being offline and dependency-free: that property is worth
keeping, and the derived half needs the linter. They are generated from one
scan of one tree, so they cannot disagree about which samples exist. Which UI5
library a control ships in is deliberately in neither: that is one taxonomy
question, and three sample repositories each answering it would be three
prefix tables that drift, so the playground's catalogue owns the mapping,
beside the library list it decides "runs here" against. The identical file
shape and the identical reasoning are in samples-controls and
samples-stack.
The categories are the header of a DESCRIPT and therefore sort
alphabetically, which puts Browser between Binding and CSS — an order
nobody learns in. So the catalogue groups the categories into stages, and
that grouping is a teaching decision written in
scripts/lib/learning-path.json and nowhere else:
{ "id": "rows", "title": "Show many rows", "blurb": "…", "categories": ["Table", "Grid Table", "List", "Tree"] }Every category belongs to exactly one stage. npm run check:catalogue
(scripts/generate-catalogue.mjs --check) fails when a category has no stage,
when two stages claim one, or when a stage names a category no sample carries.
A new category is therefore a decision somebody has to make — where in the path
does this belong — rather than a section that silently nobody can reach. Adding
a sample to an existing category needs nothing.
Those three rules used to be npm run check:overview, in the generator behind
the page. They were never about a page — they are about the path staying
attached to the tree — so they moved to the generator that publishes stage to
every consumer. Moving them surfaced that generate-catalogue.mjs had no CI
job at all: committed generated data watched only by npm run check on
somebody's laptop. The catalogues job in check-docs.yaml watches both files
now.
Everything in src/ is catalogued, which since the tree was flattened
(§1) is every class in the repository: the testing package, which existed to be
run by a check rather than learned from, is gone, so there is nothing left a
catalogue that teaches would have to lead readers around. The ZZZ helpers are
out for the reason they carry no tile (§4); they come back only as the extra
files a playground link needs to actually run.
One picture per sample used to be photographed on every deploy by
scripts/generate-screenshots.mjs, with the abap2UI5-linter's render harness.
The script went with the page; the playground's deploy takes them now
(tools/build-thumbs.mjs over there, since 2026-09-12 — for a week the
sentence before this one described a plan), from the same harness against the
same main, so what a card shows is still what the render gate checks. They
are served at /playground/samples/thumbs/<class>.png, cached by content
between deploys, and a view the harness cannot render — the z2ui5.cc
custom-control samples, mostly — has no picture, which is normal rather than
broken.
Shared across abap2UI5/samples, abap2UI5/samples-controls and
abap2UI5/samples-stack. Decided once, so nobody has to decide it again per
repository.
A class says what it IS. A sidecar records what HAPPENED to it.
| where | why | |
|---|---|---|
DESCRIPT — Titel - Kurzbeschreibung |
.clas.xml |
60 characters, hard. What ADT's object list shows |
" @summary — one sentence |
first lines of .clas.abap |
no limit. The line a catalogue puts under the title |
" @keywords — search terms |
first lines of .clas.abap |
what somebody would type who does not know the sample exists |
| upstream sample, port batch, audit findings, verification date, deviations | a sidecar (meta/<class>.json) |
not properties of the class; written by machinery; long-form; changes on a different schedule |
A sidecar does not travel. abapGit pulls src/; a meta/ folder never
reaches the SAP system. Three places that costs:
- In the system it is simply absent — which is why an overview app that needs the data has to have it baked in by a generator.
- A search engine drops somebody into the
.clas.abapon GitHub and the code is all they get. This is the same argument@docsis a full URL for. - An AI reading the class file gets no metadata unless its tooling happens
to know about
meta/.
A " comment costs the ABAP nothing — it is not "!, so SLIN/ATC does not
report an unknown tag — and it cannot desync from the class, because it is in
the class.
A deviation note with three paragraphs and a verification date is not a
property of the class; it is a log entry about a process, usually written by a
test run rather than by an author. Putting it in a " comment would bloat the
source and would still be worse structured than JSON. That belongs beside the
class, and the sidecar is right for it.
Ask: would this still be true if nobody ever ran a check again? If yes it describes the sample and belongs on the class. If it only became true because somebody did something, it belongs in the sidecar.