Skip to content

feat: add Navigation and OData V4 tutorials, align all packages#295

Open
petermuessig wants to merge 1 commit into
mainfrom
feat/integrate-navigation-odatav4-tutorials
Open

feat: add Navigation and OData V4 tutorials, align all packages#295
petermuessig wants to merge 1 commit into
mainfrom
feat/integrate-navigation-odatav4-tutorials

Conversation

@petermuessig

@petermuessig petermuessig commented Jun 29, 2026

Copy link
Copy Markdown
Contributor

What this PR does

Brings two new tutorials into the monorepo — Navigation and Routing (17 steps) and OData V4 (11 steps) — and reworks all four tutorials onto a single template so they share the same toolchain, layout, namespace, and documentation conventions.

After this PR the repo ships 4 tutorials with 69 step workspaces, all under the ui5.tutorial.<name>.stepNN naming.

Tutorials

packages/navigation/ (new)

  • 17 steps imported from the OpenUI5 demokit, restructured into the standard steps/NN/ layout.
  • App namespace renamed sap.ui.demo.navui5.tutorial.navigation across manifests, TS imports, JSDoc @namespace, XML controllerName, tsconfig paths, and HTML resource-roots.
  • Dev dependencies switched to the walkthrough set (@types/openui5, ui5-middleware-serveframework, ui5-tooling-transpile).
  • Per-step package.json names → ui5.tutorial.navigation.stepNN; ui5.yaml metadata aligned.

packages/odatav4/ (new)

  • 11 steps imported from the same demokit source.
  • Restructured solutions/steps/, root-level markdown moved into per-step README.md, shared images/ split into per-step assets/.
  • JS sources fully converted to TypeScript ES modules: Component, App.controller, model/models, initMockServer, the ~800-line sinon-based mock server, plus the view XML.
  • Hungarian variable prefixes stripped (oModelmodel, aMatchesmatches, sUrlurl, …) to match the project's TS style — confirmed against packages/walkthrough/.
  • App namespace standardised to ui5.tutorial.odatav4.

Namespace alignment of the existing tutorials

  • packages/walkthrough/ — renamed ui5.walkthroughui5.tutorial.walkthrough across ~630 files (manifests, TS imports + @namespace, XML controllerName + xmlns, tsconfig paths, HTML resource-roots, every README code snippet, step package.json names).
  • packages/quickstart/ — renamed ui5.quickstartui5.tutorial.quickstart with the same shape across 27 files; ui5.yaml metadata.name quickstart-tutorialui5.tutorial.quickstart.

Documentation

  • Per-tutorial overview READMEs (packages/{navigation,odatav4}/README.md) now mirror packages/walkthrough/README.md: each step bullet has an inline 🔗 Live Preview link plus paired <details class="ts-only"> / <details class="js-only"> 📥 Download Solution blocks.
  • Step READMEs ship with paired ```ts / ```js code blocks so the Jekyll code-couple toggle renders both flavours. The JS half is generated from the build's sanitised *-dbg.js output where applicable.
  • Folder-structure images replaced with fenced ```text ASCII trees (using .?s placeholders so the toggle flips the extensions); images deleted from per-step assets/.
  • All callout syntaxes (GitHub-flavoured alerts > [!NOTE] plus walkthrough's emoji blockquotes > 📝 **Note:** <br>) normalised to the :note: / :tip: / :info: / :caution: / :warning: shorthand mandated by _/AUTOMATE.md — 76 callouts converted.
  • Step-level "view and download all files at [demokit]" links retargeted to the published https://ui5.github.io/tutorials/... URLs so they resolve against the local dist/ via the dev server.
  • License year bumped 2025 → 2026 across all overview READMEs; ## License sections added to the new navigation and odatav4 overviews.

Tooling

  • tools/dev-server/server.js:
    • Mount dist/ under /dist/... so npm start serves the locally-built apps and ZIPs.
    • Rewrite the published https://ui5.github.io/tutorials/... URLs in rendered markdown to local /dist/... paths for the four known tutorial slugs (walkthrough, quickstart, navigation, odatav4).
    • Friendly hint page when an artifact is missing.
  • README.md: document the npm install && npm run build && npm start workflow.

Verification

  • npm install succeeds and registers all 69 workspaces under the new ui5.tutorial.* namespace.
  • npm run typecheck -ws --if-present → exit 0.
  • npm run build → exit 0. Produces dist/<tutorial>/build/NN/ apps, <tutorial>-step-NN.zip and <tutorial>-step-NN-js.zip downloads, and the rewritten dist/index.md overview for each tutorial.
  • index-cdn.html present for every webapp that bootstraps SAPUI5 (68 of 69 — walkthrough step 01 is the bare HTML "Hello World" and intentionally has none).
  • ✅ Dev-server smoke test: Live Preview links from the overview README resolve to /dist/<tutorial>/build/NN/index-cdn.html with HTTP 200.

Stats

1363 files changed: 49,009 insertions, 1,320 deletions.

JIRA: FIORITECHP1-35769

Bring two new tutorials — Navigation and Routing, OData V4 — into the
monorepo, and rework all four tutorials onto a single template so they
share the same toolchain, layout, namespace, and documentation
conventions.

Tutorials

- packages/navigation/ — 17 steps imported from the OpenUI5 demokit,
  promoted to the standard `steps/` layout, package names changed to
  `ui5.tutorial.navigation.stepNN`, ui5.yaml metadata aligned with the
  rest of the repo, dev dependencies switched to the walkthrough set
  (@types/openui5, ui5-middleware-serveframework, ui5-tooling-transpile),
  app namespace renamed `sap.ui.demo.nav` -> `ui5.tutorial.navigation`
  across manifests, TS imports, JSDoc, XML controllerName, tsconfig
  paths, and HTML resource-roots.

- packages/odatav4/ — 11 steps imported from the same demokit source,
  restructured from `solutions/` -> `steps/`, root-level markdown moved
  into per-step README.md, shared `images/` split into per-step
  `assets/`. JS sources fully converted to TypeScript ES modules
  (Component, App.controller, model/models, initMockServer, the ~800-
  line sinon-based mock server, view XML), Hungarian variable prefixes
  stripped (oModel -> model, aMatches -> matches, sUrl -> url, ...) to
  match the project's TS style. App namespace standardised to
  `ui5.tutorial.odatav4`.

Namespace alignment across the existing tutorials

- packages/walkthrough/ renamed `ui5.walkthrough` -> `ui5.tutorial.walkthrough`
  across ~630 files (manifests, TS imports + @namespace, XML
  controllerName + xmlns, tsconfig paths, HTML resource-roots, every
  README code snippet, step package.json names).
- packages/quickstart/ renamed `ui5.quickstart` -> `ui5.tutorial.quickstart`
  with the same shape across 27 files; ui5.yaml `metadata.name`
  `quickstart-tutorial` -> `ui5.tutorial.quickstart`.

After this commit, all 69 step workspaces follow the same naming
convention: `ui5.tutorial.<tutorial>.stepNN`.

Documentation

- Per-tutorial overview READMEs (packages/{navigation,odatav4}/README.md)
  now mirror packages/walkthrough/README.md: each step bullet has an
  inline `[🔗 Live Preview]` link and paired `<details class="ts-only">` /
  `<details class="js-only">` `[📥 Download Solution]` blocks.
- Step READMEs ship with paired ```ts / ```js code blocks so the
  Jekyll code-couple toggle renders both flavours. JS half generated
  from the build's sanitized `*-dbg.js` output where applicable.
- Folder-structure images replaced with fenced ```text ASCII trees
  (using `.?s` placeholders so the global toggle flips the extensions);
  images deleted from the per-step assets.
- All callout syntaxes (GitHub-flavoured alerts `> [!NOTE]` plus
  walkthrough's emoji blockquotes `> 📝 **Note:** <br>`) normalised to
  the `:note:` / `:tip:` / `:info:` / `:caution:` / `:warning:`
  shorthand mandated by `_/AUTOMATE.md`.
- Step-level "view and download all files at \[demokit\]" links
  retargeted to the published `https://ui5.github.io/tutorials/...`
  URLs so they resolve against the local dist via the dev server.
- License year bumped 2025 -> 2026 across all overview READMEs;
  `## License` sections added to the navigation and odatav4 overviews
  to match the walkthrough/quickstart convention.

Tooling

- tools/dev-server/server.js: mount `dist/` under `/dist/...` so
  `npm start` serves the locally-built apps and ZIPs; rewrite the
  published `https://ui5.github.io/tutorials/...` URLs in rendered
  markdown to the local `/dist/...` paths for the four known tutorial
  slugs (walkthrough, quickstart, navigation, odatav4); friendly hint
  page when an artifact is missing.
- README.md: document the `npm install && npm run build && npm start`
  workflow.

Verification

- `npm install` succeeds and registers all 69 workspaces under the new
  `ui5.tutorial.*` namespace.
- `npm run typecheck -ws --if-present` exits 0.
- `npm run build` exits 0; produces `dist/<tutorial>/build/NN/` apps,
  `<tutorial>-step-NN.zip` and `<tutorial>-step-NN-js.zip` downloads,
  and the rewritten `dist/index.md` overview for each tutorial.
- `index-cdn.html` present for every webapp that bootstraps SAPUI5
  (68 of 69 — walkthrough step 01 is the bare HTML "Hello World" and
  intentionally has none).
- Dev-server smoke test: Live Preview links from the overview README
  resolve to `/dist/<tutorial>/build/NN/index-cdn.html` with HTTP 200.
</pages>
</App>
</Shell>
</mvc:View>

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

some files have no empty last lines. I prefer to align this.

@@ -0,0 +1,67 @@
{
"_version": "1.60.0",

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's use manifest v2

@@ -0,0 +1,25 @@
specVersion: '3.0'

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's use specVersion '4.0'

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants