You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Some parts might not be relevant for this project (e.g. the browser-specific requirements like jQuery, CSS and accessibility in the "Contribution Content Guidelines") and the contribution process is easier (pull requests will be merged directly on GitHub).
7
+
8
+
## Requirements
9
+
10
+
Running the content of this repository locally (as opposed to following the tutorial steps) requires a [Node.js](https://nodejs.org/) version >= `20.11.0` to be installed.
11
+
12
+
## Download and Installation
13
+
14
+
> This section describes how to run the content of the repository locally and is *not* required for following the tutorial. For following the tutorial, simply start with Step 1 in the list of steps above. From there, you can also download and run the result of each step locally.
15
+
16
+
The project is set up as monorepo. All steps are located inside the `steps` folder and labelled with their step number. The monorepo uses `npm` workspaces to manage all steps together. But you can also run `npm` inside each individual step.
17
+
18
+
To set up the monorepo you first need to install all depenedencies:
19
+
20
+
```sh
21
+
npm install
22
+
```
23
+
24
+
To run any step, just execute one of the scripts from `package.json` via npm, e.g.:
25
+
26
+
```sh
27
+
# Option 1: use workspace command to start the step
28
+
npm start -w ui5.walkthrough.step01
29
+
30
+
# Option 2: change to the folder of the step and start it
31
+
cd steps/01
32
+
npm start
33
+
```
34
+
35
+
## Documentation for Tutorial Authors
36
+
37
+
### General
4
38
5
39
The setup of this project allows maintaining *one* tutorial text that covers both JavaScript and TypeScript with minimal overhead and without duplication of content.
6
40
@@ -11,12 +45,12 @@ Main features of the two-language support are:
11
45
2. Two adjacent code sections in different languages are automatically converted to a tab container which allows switching between languages.
12
46
3. File extensions writen as `.?s` appear automatically as `.js` or `.ts` depending on the current language.
13
47
14
-
## Limitations
48
+
###Limitations
15
49
16
50
The feature 3. above does not work inside code blocks (yet).
17
51
18
52
19
-
## Running the preview/dev server
53
+
###Running the preview/dev server
20
54
21
55
To immediately preview the markdown document you are writing *including* the two-language magic, simply run
22
56
@@ -35,11 +69,11 @@ npm start
35
69
A browser window will automatically open (on port 3000 or the next free port) and automatically reload on every saved change.
36
70
37
71
38
-
## Writing *one* document which covers both JavaScript and TypeScript without duplication
72
+
###Writing *one* document which covers both JavaScript and TypeScript without duplication
39
73
40
74
The following features help providing language-specific content without duplication of other content.
41
75
42
-
### 1. Language-specific Blocks of Content
76
+
####1. Language-specific Blocks of Content
43
77
44
78
When a certain part of the tutorial content (can be explanation and/or code) is only relevant for *one* of the languages (JavaScript *or* TypeScript), then enclose it within the following tags. The CSS class decides for which language it is meant!
45
79
@@ -61,7 +95,7 @@ JavaScript-only:
61
95
62
96
The `markdown="1"` part is required for markdown parsing within HTML and the `<summary>` is helpful for readers of the raw markdown view, so please use the tag structure as-is, with your actual content in between.
63
97
64
-
#### Resulting Appearance<spanclass="hidden"> in markdown view (not in the final page)</span>
98
+
#####Resulting Appearance<spanclass="hidden"> in markdown view (not in the final page)</span>
65
99
66
100
<detailsclass="ts-only"markdown="1"><summary>This section is relevant for TypeScript only</summary>
67
101
...here comes the TS-only text...
@@ -72,7 +106,7 @@ The `markdown="1"` part is required for markdown parsing within HTML and the `<s
72
106
</details>
73
107
74
108
75
-
### 2. Switchable code blocks in both languages
109
+
####2. Switchable code blocks in both languages
76
110
77
111
When a piece of code should be displayed in either JS or TS, whatever is current, then simply create two adjacent markdown-fenced code blocks. They are automatically recognized as language-specific alternatives.
78
112
@@ -91,7 +125,7 @@ Example:
91
125
92
126
> Some places where this occurs may not be properly recognized, so make sure to test it.
93
127
94
-
#### Resulting Appearance<spanclass="hidden"> in markdown view (here in markdown you still see BOTH and no tab container; the magic only happens in the dev server and in GitHub Pages)</span>
128
+
#####Resulting Appearance<spanclass="hidden"> in markdown view (here in markdown you still see BOTH and no tab container; the magic only happens in the dev server and in GitHub Pages)</span>
95
129
96
130
```js
97
131
consti=0;
@@ -101,7 +135,7 @@ const i = 0;
101
135
const i:number=0;
102
136
```
103
137
104
-
### 3. File Extensions (`.js/.ts`)
138
+
####3. File Extensions (`.js/.ts`)
105
139
106
140
When the text or a section heading mentions the name of a file that will be JavaScript or TypeScript, depending on the language, then use the file extension `.\?s`. It will automatically be switched to the current language.
107
141
@@ -110,11 +144,11 @@ Example:
110
144
In this step you create the file `Example.controller.\?s`.
111
145
```
112
146
113
-
#### Resulting Appearance<spanclass="hidden"> in markdown view (here the extension is not replaced, the replacement only happens in the dev server and in GitHub Pages)</span>
147
+
#####Resulting Appearance<spanclass="hidden"> in markdown view (here the extension is not replaced, the replacement only happens in the dev server and in GitHub Pages)</span>
114
148
115
149
In this step you create the file `Example.controller.?s`.
116
150
117
-
## Converting the JS Code to TypeScript
151
+
###Converting the JS Code to TypeScript
118
152
119
153
TODO: tool support for this functionality does not exist yet. It can, however, already be done manually.
120
154
@@ -137,5 +171,7 @@ sap.ui.define(["./BaseController"], function (__BaseController) {
137
171
138
172
Remove the function definition and the line calling the function. Rename the dependency in the `sap.ui.define` call from `__BaseController` to `BaseController`.
139
173
174
+
## Contributing with AI-generated code
175
+
As artificial intelligence evolves, AI-generated code is becoming valuable for many software projects, including open-source initiatives. While we recognize the potential benefits of incorporating AI-generated content into our open-source projects there are certain requirements that need to be reflected and adhered to when making contributions.
140
176
141
-
### TODO: Some more similar things, unless we do it in the transpiler
177
+
Please see our [guideline for AI-generated code contributions to SAP Open Source Software Projects](https://github.com/SAP/.github/blob/main/CONTRIBUTING_USING_GENAI.md) for these requirements.
0 commit comments