diff --git a/README.md b/README.md index 764780415..3cb0562ff 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,45 @@ [![REUSE status](https://api.reuse.software/badge/github.com/UI5/tutorials)](https://api.reuse.software/info/github.com/UI5/tutorials) -# UI5 Tutorials +# Tutorials -In this tutorial we'll introduce you to all major development paradigms of OpenUI5.
This section is relevant for TypeScript onlyWe'll also demonstrate the use of TypeScript with OpenUI5 and highlight the specific characteristics of this approach.
+These tutorials cover [OpenUI5](https://sdk.openui5.org/#/topic/ec699e0817fb46a0817b0fa276a249f8) application development, from beginner foundations to focused deep dives on specific concepts. Along the way you'll also use the [UI5 CLI](https://ui5.github.io/cli/stable/) for local development tooling. -## Description +All tutorials are available in both **TypeScript** and **JavaScript**. Use the language toggle at the top of each tutorial page to switch between versions. -We first introduce you to the basic development paradigms like *Model-View-Controller* and establish a best-practice structure of our application. We'll do this along the classic example of β€œHello World” and start a new app from scratch. Next, we'll introduce the fundamental data binding concepts of OpenUI5 and extend our app to show a list of invoices. We'll continue to add more functionality by adding navigation, extending controls, and making our app responsive. We'll also have look at the testing features and the built-in support tools of OpenUI5. +No prior OpenUI5 experience is needed. Basic familiarity with HTML, CSS, and JavaScript (or TypeScript) is assumed. -## Tutorials +## Learning path -This repository contains following tutorials: -- [Quickstart](./packages/quickstart/) -- [Walkthrough](./packages/walkthrough/) -- [Data Binding](./packages/databinding/) -- [Navigation and Routing](./packages/navigation/) -- [OData V4](./packages/odatav4/) +| Tutorial | Type | Content +|---|---|---| +| [Quickstart](./packages/quickstart/) | Foundation | Get a first OpenUI5 app running in minutes, covering bootstrapping, MVC basics, and a quick showcase of data binding and navigation. | +| [Walkthrough](./packages/walkthrough/) | Foundation | Builds a complete app from scratch, covering MVC, data binding, navigation, custom controls, testing, and production build. | +| [Data Binding](./packages/databinding/) | Deep dive | Explores the core binding modes in depth along with formatting, data types, and validation. | +| [Navigation and Routing](./packages/navigation/) | Deep dive | Covers the core routing API through a realistic employee app: URL parameters, transitions, bookmarkable states, lazy loading, and error handling. | +| [OData V4](./packages/odatav4/) | Deep dive | Builds a list/detail app against an OData V4 service covering CRUD operations, filtering, sorting, batch groups, and OData actions. | + +The live published site is at ****. + +## Repository structure + +``` +packages/ + / + docs/ # Markdown source for the tutorial steps + steps/ # One self-contained app per step +``` + +Each step under `steps/` is a standalone npm workspace package named `ui5.tutorial..stepNN`. + +The JS/TS language toggle is implemented via CSS classes (`ts-only`, `js-only`) on elements in the markdown source. The local dev server and the GitHub Pages site both apply the toggle at render time. On plain github.com those elements render as standard collapsed HTML details. ## Running locally The repository is set up as an npm workspaces monorepo. Each tutorial step under `packages/*/steps/*` is a self-contained app you can run standalone, and the root build orchestrator produces a unified preview that mirrors the published GitHub Pages site. +**Prerequisites:** +Node.js 20.11.0 or higher, or v22 or higher (v21 is not supported). The UI5 CLI is installed automatically as part of `npm install`. + ```sh # 1) install dependencies for every step npm install diff --git a/packages/quickstart/README.md b/packages/quickstart/README.md index cd306b21b..d79572f09 100644 --- a/packages/quickstart/README.md +++ b/packages/quickstart/README.md @@ -1,28 +1,24 @@ -# OpenUI5 Quickstart +# Quickstart Tutorial -In this tutorial we'll introduce you to all major development paradigms of OpenUI5.
This section is relevant for TypeScript onlyWe'll also demonstrate the use of TypeScript with OpenUI5 and highlight the specific characteristics of this approach.
+In this tutorial we'll get you up and running with OpenUI5 quickly with a hands-on first app. ## Description -We first introduce you to the basic development paradigms like *Model-View-Controller* and establish a best-practice structure of our application. We'll do this along the classic example of β€œHello World” and start a new app from scratch. Next, we'll introduce the fundamental data binding concepts of OpenUI5 and extend our app to show a list of invoices. We'll continue to add more functionality by adding navigation, extending controls, and making our app responsive. We'll also have look at the testing features and the built-in support tools of OpenUI5. +We set up the development environment and bootstrap OpenUI5 in an HTML page with a simple "Hello World" button. We then extend the app to follow the "Model-View-Controller" pattern by introducing an XML view and a controller. Finally, we add a second page and showcase key OpenUI5 concepts like data binding, JSON models, and navigation in action. ### Preview -![Preview of the OpenUI5 application that is going to be built in this tutorial. Contains a Hello World upper part with buttons and a text input. The lower part shows list of invoices with details, grouped by vendor names.](steps/03/assets/loio79e1157d948c488c9717ef840fa9b396_LowRes.png). +![The second page of the final quickstart app titled 'Create Enterprise-Ready Web Apps with Ease', showing the OpenUI5 phoenix logo, a 'This is UI5!' heading, six feature InfoLabels, and an expandable 'Are you ready?' panel.](steps/03/assets/loio79e1157d948c488c9717ef840fa9b396_LowRes.png) -> πŸ’‘ -> You don't have to do all tutorial steps sequentially, you can also jump directly to any step you want. Just download the code from the previous step and make sure that the application runs as intended. -> -> You can view the samples for all steps here in this repository. -> +*The second page of the finished app, reached by pressing the Go! button* ### Steps -The tutorial consists of the following steps. To start, just open the first link - you`ll be guided from there. +The tutorial consists of the following steps. To start, just open the first link - you'll be guided from there. Each step also has a download link so you can jump in at any point with the complete code from the previous step, then run `npm install` and `npm start` in the unzipped folder. - **[Step 1: Ready...](steps/01/README.md)** β€” Let's get you ready for your journey! We bootstrap OpenUI5 in an HTML page and implement a simple "Hello World" example. ([πŸ”— Live Preview](https://ui5.github.io/tutorials/quickstart/build/01/index-cdn.html) \| [πŸ“₯ Download Solution](https://ui5.github.io/tutorials/quickstart/quickstart-step-01.zip) (TS)[πŸ“₯ Download Solution](https://ui5.github.io/tutorials/quickstart/quickstart-step-01-js.zip) (JS) ) - **[Step 2: Steady...](steps/02/README.md)** β€” Now we extend our minimalist HTML page to a basic app with a view and a controller. ([πŸ”— Live Preview](https://ui5.github.io/tutorials/quickstart/build/02/index-cdn.html) \| [πŸ“₯ Download Solution](https://ui5.github.io/tutorials/quickstart/quickstart-step-02.zip) (TS)[πŸ“₯ Download Solution](https://ui5.github.io/tutorials/quickstart/quickstart-step-02-js.zip) (JS) ) -- **[Step 3: Go!](steps/03/README.md)** β€” Now it is time to build our first little UI by replacing the "Hello World" text in the HTML body by the OpenUI5 control sap/m/Text. In the beginning, we will use the JavaScript control interface to set up the UI, the control instance is then placed into the HTML body. ([πŸ”— Live Preview](https://ui5.github.io/tutorials/quickstart/build/03/index-cdn.html) \| [πŸ“₯ Download Solution](https://ui5.github.io/tutorials/quickstart/quickstart-step-03.zip) (TS)[πŸ“₯ Download Solution](https://ui5.github.io/tutorials/quickstart/quickstart-step-03-js.zip) (JS) ) +- **[Step 3: Go!](steps/03/README.md)** β€” Finally, we add a second page to our app and showcase key OpenUI5 concepts like navigation, data binding, and JSON models in a hand-on playground. ([πŸ”— Live Preview](https://ui5.github.io/tutorials/quickstart/build/03/index-cdn.html) \| [πŸ“₯ Download Solution](https://ui5.github.io/tutorials/quickstart/quickstart-step-03.zip) (TS)[πŸ“₯ Download Solution](https://ui5.github.io/tutorials/quickstart/quickstart-step-03-js.zip) (JS) ) ## License diff --git a/packages/quickstart/steps/01/README.md b/packages/quickstart/steps/01/README.md index abc1f14b2..677bf497c 100644 --- a/packages/quickstart/steps/01/README.md +++ b/packages/quickstart/steps/01/README.md @@ -234,7 +234,7 @@ To use OpenUI5, execute the following command: ui5 use OpenUI5 ``` -To use install the required UI5 libraries, execute the following command: +To use install the required OpenUI5 libraries, execute the following command: ```sh ui5 add sap.m sap.tnt sap.ui.core sap.ui.layout themelib_sap_horizon @@ -274,7 +274,7 @@ Let's break down what each package does: #### ui5.yaml -Next, we have to configure the tooling extension we installed from npm to our UI5 CLI setup, so we can use them in our project. To hook a custom task into a certain build phase of a project, it needs to reference another task that will get executed before or after it. The same applies for a custom middleware: +Next, we have to configure the tooling extension we installed from npm to our UI5 CLI setup, so we can use them in our project. To hook a custom task into a certain build phase of a project, it needs to reference another task that will get executed before or after it. The same applies for a custom middleware:
- For the `ui5-tooling-transpile-task` we specify that this should happen after the`replaceVersion` task. diff --git a/packages/walkthrough/README.md b/packages/walkthrough/README.md index d640abe21..94024be48 100644 --- a/packages/walkthrough/README.md +++ b/packages/walkthrough/README.md @@ -1,4 +1,4 @@ -# OpenUI5 Walkthrough +# Walkthrough Tutorial In this tutorial we'll introduce you to all major development paradigms of OpenUI5.
This section is relevant for TypeScript onlyWe'll also demonstrate the use of TypeScript with OpenUI5 and highlight the specific characteristics of this approach.
diff --git a/tools/builder/prepare-gh-pages.js b/tools/builder/prepare-gh-pages.js index 4e850e2c7..fb14cb1fb 100644 --- a/tools/builder/prepare-gh-pages.js +++ b/tools/builder/prepare-gh-pages.js @@ -90,7 +90,7 @@ function removeTSfromUI5YAML(ui5yaml) { } function rewriteLinks(file) { let permalink = file.split("dist/")[1].replace(".md", ".html"); - const title = "UI5 Tutorials"; + const title = "OpenUI5 Tutorials"; let content = `---\ntitle: ${title}\npermalink: ${permalink}\n---\n\n${readFileSync(file, { encoding: "utf8"})}`; content = content.replace(/README\.md/g, "index.html"); content = content.replace(/\.\/packages\//g, "./"); diff --git a/tools/dev-server/ghpage-template.hbs b/tools/dev-server/ghpage-template.hbs index 579dee24a..e5b726f13 100644 --- a/tools/dev-server/ghpage-template.hbs +++ b/tools/dev-server/ghpage-template.hbs @@ -63,7 +63,7 @@

- UI5 Tutorials + OpenUI5 Tutorials

{{{bodyContent}}}