GS_02_Set_up_your_project - XLRIT/gears GitHub Wiki

Follow these steps to set up your first project:

1. Create a project in Git

  1. Go to https://www.gitlab.com
  2. On left top click Menu then Project then Create new project
  3. Choose Create blank project
  4. Give the project a name (in this example we will call the project getting-started).
  5. Click button Create project. The result should look a bit like this:

2. Clone the Git project locally and open it in VS Code

  1. Click on the Clone button.
  2. Click Visual Studio Code (HTTPS)
  3. If needed click Open link in Visual Studio Code
  4. Now you will be asked to select the repository location. For all Git project we will be assuming c:\git as the standard repository location. If you have not created this location you can do that now:

  1. When you are in the folder c:\git you can click Select Repository Location.

If you do this for the first time, you may be asked to log in to GitLab from VS Code. You can choose Sign in with your browser and re-logon into GitLab. After you have done this.

  1. You should get a notification in VS Code in the right lower corner of VS Code. In that notification click on Open in New Window. The result should look a bit like this:

You can also open a project from the Windows Explorer by right clicking on the folder (in this example c:\git\getting-started) and choosing Open with VS Code or directly from VS Code with menu File then Open Folder.

3. Add standard files and folders

  1. Right click on a location in the Explorer Side bar and choose New Folder to add subfolders to your project. The following standard subfolders should be added:
Sub folder names Explanation
data contains all data to test or run your application
resources contains the technical files that you need to run the application
scenarios contains test scenario's that you can use to automatically test your application
specs contains the result requirement specification files.
  1. Right click on an empty location Explorer Side bar and choose New File to add the following file to to your project:
  • File name: gears.json
  • Content:
{
  "projectName": "getting_started",
  "projectVersion": "0.1-SNAPSHOT",
  "generatorVersion": "1.6.6",
  "runtimeVersion": "1.6.7",
  "runnerVersion": "0.22",
  "generatorOptions": {
    "enableStartForms": true,
    "tableNamePrefix": "GS"
  },
  "plugins": [
    "com.xlrit.gears.runtime:gears-runtime-plugin-jasper",
    "com.xlrit.gears.runtime:gears-runtime-plugin-xdocreport",
    "com.xlrit.gears.runtime:gears-runtime-plugin-mail"
  ]
}

Most should be clear because it is only saying which version you are using. In most cases you can simply leave it. But the following may require a little more explanation:

Line Explanation
"projectName": "getting_started", Folder name for the sources that GEARS generates. Do not use spaces here. Use underscores (_) instead.
"projectVersion": "0.1-SNAPSHOT", version of the app you are making. The -SNAPSHOT indicates your actively developing this app and not releasing it to the world.
"enableStartForms": true, When set to true the process only starts after the user has filled in and submitted the first task. When set to false the process first starts and then the first form is opened. It is best to keep this to true.
"tableNamePrefix": "GS" Each database table that GEARS creates for you, will start with this prefix followed by an underscore. Later you will see that this makes it easier to find your "own" tables. You can choose anything you like but it is often an abrieviation of the name of the system. So in this case your system is called "Getting Started", so the prefix is GS.
"plugins": [ Extra functionality can be added in the form of plugins. For instance jasper is for creating fancy reports, xdocreport is for creating docx and pfd files from docx templates and mail is for (you guessed it) creating and sending e-mails. You will learn about those later when you follow this getting started.
  1. Right click on the subfolder resources and choose New File to add the following file to to your project:
  • File name: application.yml
  • Content:
gears:
  frontend:
    name:               Getting started
  init:
    create-demo-users:  true
  testing:
    enabled:            true
  mail:
    enabled:            true
    cron:               0/10 * * ? * * *
spring:
  banner:
    location:           classpath:banner.txt
  datasource:
    url:                'jdbc:h2:mem:gears;DB_CLOSE_ON_EXIT=FALSE'
  • Explanation: the explanation about this file is in the table below
Line Explanation
name: Getting started Name if the app as displayed in the app itself.
create-demo-users: true If demo users are created automatically. For instance user demo which you will use later in this getting started
testing:     enabled: true Makes it possible to run test scenarios. Should always be set to false before you deploy you app in an operational environment. If not your app will be easy to hack.
mail:     enabled: true If your app can send mails automatically, setting this to true will actually send real emails. If set to false the emails will only be stored in the database (in table SYS_MAIL).
cron: 0/10 * * ? * * * A so called "cron" schedule that defines how often your app will check if there are new mails that should be send. See this site for more explanation and an easy way create your own cron schedules.
banner:     location: classpath:banner.txt defines the location and name of the banner. The classpath part is a synonym for the resources folder. You should not have to change this.
url: 'jdbc:h2:mem:gears;DB_CLOSE_ON_EXIT=FALSE' The exact URL to the database your app will be using. This is also called the "database connection string". The current value refers to the in memory database you will often use during development of your app. When you would like to
  1. Right click on the subfolder resources and choose New File to add the following file to to your project:
  • File name: banner.txt
  • Content: this is where a first little bit of fun starts. Because the content of this file will be filled with ASCII art. There are many ways to create ASCII art, but the easiest way is to let a site do that for you. For example this one: https://patorjk.com/software/taag/. Go to this site, then change Type Something to Fun starts. Also change the Font to ANSI Shadow. Then click the button Select & Copy. And past the copied result into this banner.txt file. The result should look like this:

ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā•—ā–ˆā–ˆā•—   ā–ˆā–ˆā•—ā–ˆā–ˆā–ˆā•—   ā–ˆā–ˆā•—    ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā•—ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā•— ā–ˆā–ˆā–ˆā–ˆā–ˆā•— ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā•— ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā•—ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā•—
ā–ˆā–ˆā•”ā•ā•ā•ā•ā•ā–ˆā–ˆā•‘   ā–ˆā–ˆā•‘ā–ˆā–ˆā–ˆā–ˆā•—  ā–ˆā–ˆā•‘    ā–ˆā–ˆā•”ā•ā•ā•ā•ā•ā•šā•ā•ā–ˆā–ˆā•”ā•ā•ā•ā–ˆā–ˆā•”ā•ā•ā–ˆā–ˆā•—ā–ˆā–ˆā•”ā•ā•ā–ˆā–ˆā•—ā•šā•ā•ā–ˆā–ˆā•”ā•ā•ā•ā–ˆā–ˆā•”ā•ā•ā•ā•ā•
ā–ˆā–ˆā–ˆā–ˆā–ˆā•—  ā–ˆā–ˆā•‘   ā–ˆā–ˆā•‘ā–ˆā–ˆā•”ā–ˆā–ˆā•— ā–ˆā–ˆā•‘    ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā•—   ā–ˆā–ˆā•‘   ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā•‘ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā•”ā•   ā–ˆā–ˆā•‘   ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā•—
ā–ˆā–ˆā•”ā•ā•ā•  ā–ˆā–ˆā•‘   ā–ˆā–ˆā•‘ā–ˆā–ˆā•‘ā•šā–ˆā–ˆā•—ā–ˆā–ˆā•‘    ā•šā•ā•ā•ā•ā–ˆā–ˆā•‘   ā–ˆā–ˆā•‘   ā–ˆā–ˆā•”ā•ā•ā–ˆā–ˆā•‘ā–ˆā–ˆā•”ā•ā•ā–ˆā–ˆā•—   ā–ˆā–ˆā•‘   ā•šā•ā•ā•ā•ā–ˆā–ˆā•‘
ā–ˆā–ˆā•‘     ā•šā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā•”ā•ā–ˆā–ˆā•‘ ā•šā–ˆā–ˆā–ˆā–ˆā•‘    ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā•‘   ā–ˆā–ˆā•‘   ā–ˆā–ˆā•‘  ā–ˆā–ˆā•‘ā–ˆā–ˆā•‘  ā–ˆā–ˆā•‘   ā–ˆā–ˆā•‘   ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā•‘
ā•šā•ā•      ā•šā•ā•ā•ā•ā•ā• ā•šā•ā•  ā•šā•ā•ā•ā•    ā•šā•ā•ā•ā•ā•ā•ā•   ā•šā•ā•   ā•šā•ā•  ā•šā•ā•ā•šā•ā•  ā•šā•ā•   ā•šā•ā•   ā•šā•ā•ā•ā•ā•ā•ā•

You can jump into more info about these files which can be found in Configure GEARS generator but you can also continue this "Getting started" in which all of these things will be explained.

And for those that are a bit lazy: here is a script you can copy paste in a (git) bash terminal (which you can open from VS Code with F1 -> Terminal: Create New Terminal (with Profile) and choose Git Bash):

mkdir data
mkdir resources
mkdir scenarios
mkdir specs
printf '{\n  "projectName": "getting_started",\n  "projectVersion": "0.1-SNAPSHOT",\n  "generatorVersion": "1.6.6",\n  "runtimeVersion": "1.6.7",\n  "runnerVersion": "0.22",\n  "generatorOptions": {\n    "enableStartForms": true,\n    "tableNamePrefix": "GS"\n  },\n  "plugins": [\n    "com.xlrit.gears.runtime:gears-runtime-plugin-jasper",\n    "com.xlrit.gears.runtime:gears-runtime-plugin-xdocreport",\n    "com.xlrit.gears.runtime:gears-runtime-plugin-mail"\n  ]\n}' > gears.json
printf "gears:\n  frontend:\n    name:               Getting started\n  init:\n    create-demo-users:  true\n  testing:\n    enabled:            true\n  mail:\n    enabled:            true\n    cron:               0/10 * * ? * * *\nspring:\n  banner:\n    location:           classpath:banner.txt\n  datasource:\n    url:                'jdbc:h2:mem:gears;DB_CLOSE_ON_EXIT=FALSE'" > resources/application.yml
printf "\nā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā•—ā–ˆā–ˆā•—   ā–ˆā–ˆā•—ā–ˆā–ˆā–ˆā•—   ā–ˆā–ˆā•—    ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā•—ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā•— ā–ˆā–ˆā–ˆā–ˆā–ˆā•— ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā•— ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā•—ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā•—\nā–ˆā–ˆā•”ā•ā•ā•ā•ā•ā–ˆā–ˆā•‘   ā–ˆā–ˆā•‘ā–ˆā–ˆā–ˆā–ˆā•—  ā–ˆā–ˆā•‘    ā–ˆā–ˆā•”ā•ā•ā•ā•ā•ā•šā•ā•ā–ˆā–ˆā•”ā•ā•ā•ā–ˆā–ˆā•”ā•ā•ā–ˆā–ˆā•—ā–ˆā–ˆā•”ā•ā•ā–ˆā–ˆā•—ā•šā•ā•ā–ˆā–ˆā•”ā•ā•ā•ā–ˆā–ˆā•”ā•ā•ā•ā•ā•\nā–ˆā–ˆā–ˆā–ˆā–ˆā•—  ā–ˆā–ˆā•‘   ā–ˆā–ˆā•‘ā–ˆā–ˆā•”ā–ˆā–ˆā•— ā–ˆā–ˆā•‘    ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā•—   ā–ˆā–ˆā•‘   ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā•‘ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā•”ā•   ā–ˆā–ˆā•‘   ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā•—\nā–ˆā–ˆā•”ā•ā•ā•  ā–ˆā–ˆā•‘   ā–ˆā–ˆā•‘ā–ˆā–ˆā•‘ā•šā–ˆā–ˆā•—ā–ˆā–ˆā•‘    ā•šā•ā•ā•ā•ā–ˆā–ˆā•‘   ā–ˆā–ˆā•‘   ā–ˆā–ˆā•”ā•ā•ā–ˆā–ˆā•‘ā–ˆā–ˆā•”ā•ā•ā–ˆā–ˆā•—   ā–ˆā–ˆā•‘   ā•šā•ā•ā•ā•ā–ˆā–ˆā•‘\nā–ˆā–ˆā•‘     ā•šā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā•”ā•ā–ˆā–ˆā•‘ ā•šā–ˆā–ˆā–ˆā–ˆā•‘    ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā•‘   ā–ˆā–ˆā•‘   ā–ˆā–ˆā•‘  ā–ˆā–ˆā•‘ā–ˆā–ˆā•‘  ā–ˆā–ˆā•‘   ā–ˆā–ˆā•‘   ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā•‘\nā•šā•ā•      ā•šā•ā•ā•ā•ā•ā• ā•šā•ā•  ā•šā•ā•ā•ā•    ā•šā•ā•ā•ā•ā•ā•ā•   ā•šā•ā•   ā•šā•ā•  ā•šā•ā•ā•šā•ā•  ā•šā•ā•   ā•šā•ā•   ā•šā•ā•ā•ā•ā•ā•ā•\n\n" > resources/banner.txt

Note that for new projects (like the one you will do yourself) you can use this trick to get started a bit quicker.

4. Do it yourself

Of course the best way to try if you've learned some skills is to create a system on your own. And that is exactly what I am asking you to do now. Here is the situation and you assignment:

4.1. Situation: a school needs a new special school system

A special kind of school needs a special kind of school system. The standard school systems such as Magister work well and have a lot of standard functionality, but these standard systems are not able to provide the special functionality that the school needs. It is your job to create a new school system.

4.2. Assignment: set up a new project for this "school-system"

In this page you already set up a project called getting-started. In this assignment you will setup a project called school-system. VS Code will give you the option to do it in a new window. If so please choose that option.