-
Notifications
You must be signed in to change notification settings - Fork 37
Functions
The following functions are already implemented:
- installDevonfwIde
- restoreDevonfwIde
- restoreWorkspace
- changeWorkspace
- executeCommand
- installCobiGen
- cobiGenJava
- createDevon4jProject
- buildJava
- createFile
- changeFile
- createFolder
- cloneRepository
- runServerJava
- buildNg
- npmInstall
- dockerCompose
- downloadFile
- displayContent
- adaptTemplatesCobiGen
- createDevon4ngProject
- addSetupScript
- The tools you want to install within the devonfw ide: string array
- Optional: The version of the ide to install
installDevonfwIde(["java","mvn"], "2020.08.001")
- The tools you want to install within the devonfw ide: string array
- Optional: The version of the ide to install
restoreDevonfwIde(["java","mvn"], "2020.08.001")
In the Katacoda environment the installation of the devonfw IDE is executed in a startup script.
- (Optional) Name of the workspace repository {"workspace": string} (Default is the playbook-name)
User(Optional) flag: --user value: GitHub-username (Default is 'devonfw-tutorials')
You can use a forked workspace-repository, if you add the username as argument. If the runner cannot find the workspace repository in the your repositories, it will use devonfw-tutorials instead.
Branch(Optional) flag: --branch value: the working branch (Default is its default-branch)
You can use a different branch, if you add the working branch as argument. If the runner cannot find the branch in the cloned repository, it will use the default branch instead.
buildRun.sh --user [username] --branch [branch]
restoreWorkspace() will clone "https://github.com/devonfw-tutorials/[playbook-name]" into the workspace directory.
restoreWorkspace({"workspace": [name]}) will clone "https://github.com/devonfw-tutorials/[name]" into the workspace directory.
buildRun.sh --user [GitHub-name] --branch [branch] restoreWorkspace() will run "git clone https://github.com/[GitHub-name]/[playbook-name]" and checkout in branch [branch]
workspace The default name of the workspace repository is a concatenation of "workspace-" and the name of your playbook-folder. If you want to use another repository as workspace, you can specify the ending with {"workspace": [name]}. example "workspace-devon4ng" -> {"workspace" : "devon4ng"}
local repository You can use a local repository as workspace in the console environment for your tutorial. Clone the forked repository next to the tutorial-compiler folder. Before cloning the GitHub repository, the console runner will always check, if there is a 'workspace-[name]'-folder next to the tutorial compiler first, and will use it instead.
Keep in mind, that it is a feature only implemented in the console environment. Other runners will clone the environment from GitHub.
|--tutorial-compiler
|--tutorials
|--workspace-devon4ng
workspace directory
If you call 'restoreDevonfwIde' or 'installDevonfwIde' before the 'restoreWorkspace'-function the workspace directory remains:
`'/root/workspaces/main'`
If you don't call them, the workspace is changed to:
`'/root/workspaces'`
Learn more about the workspace directory and working directory on Structure
- path to a new workspace (relative to working directory)
changeWorkspace("devonfw/workspaces/project") will set the workspace directory to "[working directory]/devonfw/workspaces/project"
Learn more about the workspace directory and working directory on Structure
- The command that will be executed on Windows
- The command that will be executed on Linux
- Json-object with optional fields
- (Optional) Directory where the command will be executed, if not in current directory (relative to workspace){"dir": string}
- (Optional) Synchronous or asynchronous process. Use asynchronous when starting a server. Default is synchronous. {"asynchronous": boolean}
- (Optional) Array of arguments {"args": string[]}
- Assert information needed if you start a server to check server availability. Only required when you start a asynchronous server.
It is needed to pass a command for Windows and also for Linux-based systems because both systems will always be tested.
startupTime = Time in seconds to wait before checking if the server is running port: Port on which the server is running path: The URL path on which is checked if the server is running interval: The availability of the server is checked in the given interval
- (Required) port: will throw error if no port is given.
- (Optional) path: subpath which should be pinged, i.e: if localhost:8081/jumpthequeue should be checked path should be "jumpthequeue". DEFAULT: ""
- (Optional) interval: interval in seconds in which the server should be pinged until it is available or timeouted. DEFAULT: 5 seconds
- (Optional) startupTime: seconds until a timeout will occur and an error will be thrown. DEFAULT: 10 minutes
executeCommand("node", "node" ,{"args": ["-v"]}) Will create a command for executing node -v .
executeCommand("somePollingScript.ps1","bash somePollingScript.sh", {"dir": "data/setup","asynchronous": true, "args": ["--params 5"]}) Will create a command to execute the script in the directory with the parameter --params 5 and in a new terminal.
executeCommand("someServerScript.ps1","bash someServerScript.sh", {"asynchronous": true, "args":["-port 8080"] },{"port":8080 , "startupTime": 20, "path": "some/path/", "interval": 2}) Starting a server in a new terminal. You have to specify the port for testing, the other parameters are optional. The startupTime can specify how long the runner will wait for a response from the server process and with interval you can set the frequenzy for the server testing. The path is the subpath from your server that should be reached.
- No parameters
installCobiGen()
This function is used for code generation inside Java file i.e. Entity class in Java.
This function consist of two parameters.
- First parameter:
- Required
- Type- String
- Description- The path to the Java file you want to generate code for.
- Second parameter:
- Required
- Type- Array of Integers
- Description- It is the array of numbers that represent the templates that CobiGen uses to generate code.
cobiGenJava("path/to/java/file/MyEntity.java",[1,3,5,6,8])
| Number | Description |
|---|---|
| 1 | CRUD logic: Generates the logic layer and implementations for some use cases. |
| 3 | CRUD REST services: Generates the service layer with CRUD operations for using in REST services. |
| 5 | TO's: Generates the related Transfer Objects. |
| 6 | Entity infrastructure: Creates the entity main interface and edits (by a merge) the current entity to extend the newly generated classes. |
| 8 | CRUD SpringData Repository: Generates the entity repository (that contains the CRUD operations) in the data access layer. |
Note:
-
User needs to execute this command manually.
-
You need to add installCobiGen() and adaptTemplatesCobiGen() functions before adding this function for CobiGen installation and adapting the Cobigen Templates respectively.
-
CobiGen CLI is used for execution of these functions. You can find more information related to CobiGen CLI click here.
-
To execute this function, devonfw-ide must be installed.
- The base package name
createDevon4jProject("com.mycustomer.myapplication")
- The project directory, relative to workspace.
- (Optional) Indicator whether tests should be run. Default is false.
buildJava("cobigenexample", true)
- Path of the file to be created (relative path to the workspace directory).
- (Optional) Path of the file to get the content from. Relative to the playbook directory
createFile("cobigenexample/core/src/main/java/com/example/application/cobigenexample/customermanagement/dataaccess/api/CustomerEntity.java", "files/CustomerEntity.java")
- Path of the file to be changed (relative path to the workspace directory)
- Path of the file to get the content from or a string, that should be inserted.(relative path to the playbook directory)
- (Optional) Name of a placeholder
- (Optional) Line number where u want to insert your code. (Possible lines are: 1...n+1 for N = number of existing lines. File cant be empty)
changeFile("cobigenexample/core/src/main/java/com/example/application/cobigenexample/customermanagement/dataaccess/api/CustomerEntity.java", { "file": "files/Placeholder.java", "placeholder": "private static final long serialVersionUID = 1L;" })
If you want to add content from a file: {"file": "[path]"} If you want to add a string to a file: {"content": "[string]"} If you want to add different contents for the katacoda and console runner, then use the properties "fileConsole" and "fileKatacoda" or "contentConsole" and "contentKatacoda": {"fileConsole": "[pathToConsoleFile]", "fileKatacoda": "[pathToKatacodaFile]"} If you want to insert some content at a specific line, then use "lineNumber" and dont use a placeholder: {"lineNumber": "[Line]"}
example:{...,"placeholder": "private int age;"}
| Before | Content or File | After |
|---|---|---|
private int age; |
private int age; |
private int age; |
The usage of the line number function requires having VSCode installed on your System. Not having VSCode installed will not create any output for Katacoda.
If you want to insert content into your code between two existing lines, take the previous line as your placeholder or use the option to insert at a line number. Add your placeholder into the new file or string, otherwise it will be replaced entirely.
A placeholder is optional. If you do not define a placeholder, the content in the existing file will be simply replaced by the new content.
Please try not to use custom placeholders. Keep in mind that you might want to build the project before changing them. Custom placeholders with a comment-syntax (e.g. "//PLACEHOLDER") will be removed by the console-environment and others might cause errors.
The option to insert at a linenumber uses a placeholder inserted by a script and just adds it at the step you also insert the content.
- Path of the folder to be created, relative to the workspace directory. Subdirectories are also created.
createFolder("directoryPath/subDirectory")
- Path into which the repository is to be cloned, relative to workspace.
- Git repository URL
cloneRepository("", "https://github.com/devonfw-tutorials/tutorial-compiler.git") Repository will be cloned directly into the workspace directory.
cloneRepository(devonfw-tutorials", "https://github.com/devonfw-tutorials/tutorial-compiler.git") Repository will be cloned into a newly created subdirectory devonfw-tutorials.
- Path to the server directory within the java project.
- Assertion information. Only needed for the console runner to check if the server was started properly.
runServerJava("devonfw/workspaces/main/jump-the-queue/java/jtqj/server", { "startupTime": 40, "port": 8081, "path": "jumpthequeue" })
startupTime = Time in seconds to wait before checking if the server is running port: Port on which the server is running path: The URL path on which is checked if the server is running
If the tutorial should be tested on the console environment, you have to specify a port.
- Path to the project where the dependencies from the package.json file are to be installed.
- Json-object: Name of a package, global or local installation, or array of npm arguments
- (Optional) name of a package {"name": string }
- (Optional) global or local installation. Default is local, therefore false {"global" : boolean }
- (Optional) array of npm arguments {"args": string[]}
npmInstall("jump-the-queue/angular", {"name": "@angular/cli", "global": true, "args": ["--save-dev"]}) will run 'npm install -g --save-dev @angular/cli' in the directory 'jump-the-queue/angular'.
npmInstall("my-thai-star/angular") will run 'npm install' in the directory 'my-thai-star/angular'
- Path to the directory where the docker-compose.yml file is located, relative to workspace.
- Assertion information. Only needed for the console runner to check if the server was started properly.
dockerCompose("my-thai-star", { "startupTime": 600, "port": 8081, "path": "" })
startupTime = Time in seconds to wait before checking if the server is running port: Port on which the server is running path: The URL path on which is checked if the server is running
If the tutorial should be tested on the console environment, you have to specify a port.
- URL of the file to be downloaded.
- Name of file.
- (Optional) Downloads file to a given directory relative to workspace. Directory is created, if its not existing.
downloadFile("https://bit.ly/2BCkFa9", "file", "downloads")
- Path to the angular project, relative to workspace
- (Optional) Custom output directory.
buildNg("exampleAngularProject") Will build the angular project to default output directory defined in angular.json outputPath key, normally set to dist/.
buildNg("exampleAngularProject", "testOutput") Will build the angular project to output directory testOutput.
- Path to the angular project from which the frontend server is to be started.
- Assertion information. Only needed for the console runner to check if the server was started properly.
runClientNg("jump-the-queue/angular", { "startupTime": 200, "port": 4200, "path": "" })
startupTime = Time in seconds to wait before checking if the server is running port: Port on which the server is running path: The URL path on which is checked if the server is running
If the tutorial should be tested on the console environment, you have to specify a port.
- The title of the step.
- An array of json objects with files, content, or images to be rendered within the Katacoda step. The use for this function is to display an image and some descriptive text. No Katacoda syntax is allowed in the files or the content!
- (Optional) Path to the current directory where the user is located (relative to the workspace directory). Only needed if the directory is changed within this step.
display("Step title", [{ "file": "files/description.asciidoc" }, { "content": "This is just plain content." }, { "image": "files/image.png" }])
Available attributes in the json objects:
- file: Path to a file whose content is to be displayed in the Katacoda step (e.g. .asciidoc or .txt file). The file should be following the formating of asciidoc files.
- content: Plain text to be displayed in the Katacoda step. This Text should be following the formating of asciidoc files.
- image: Path to an image to be displayed in the Katacoda step.
- You can add headers to structure your text. The generated headers are shown in the examples below. The headers should fit into the overall structure of the generated wiki so level 1 header are not allowed, but the other header can be used at your judgement.
- A list always needs an empty newline between the last row and the list.
- Use asciidoc style of links
Existing header structure
= Level 1: tutorial title
== Level 2: subtitle
=== Level 3: prerequisites and learning goals
== Level 2: steptitle
=== Level 3: titles from functions
==== Level 4: subtitles from functions
== Level 2: conclusion
List:
This an unordered List (The empty line is necessary)
* First Item
* Second Item
Link:
The tutorials repository can be found https://github.com/devonfw-tutorials/tutorials/issues[here].
- No parameters
adaptTemplatesCobiGen()
- Name of the Project.
- Path to where the Project should be created (relative to workspace). Folder should exist.
- (Optional) String array of parameters, according to https://angular.io/cli/new.
createDevon4ngProject("exampleAngularProject", "") Will create the angular project to the current workspace with the name exampleAngularProject.
createDevon4ngProject("exampleAngularProject", "projects", ["--verbose"]) Will create the angular project to the directory projects within the current workspace and adds more details to output logging.
This command also works if the devonfw IDE is not installed, but then you have to make sure that the Angular cli is installed.
- Path of the script (Linux). Relative to the playbook directory
- Path of the script (Windows). Relative to the playbook directory
addSetupScript("assets/createProjectScript.sh", "assets/createProjectScript.ps1")
- Path of the file to be opened (relative path to the workspace directory)
openFile("cobigenexample/core/src/main/java/com/example/application/cobigenexample/customermanagement/dataaccess/api/CustomerEntity.java")