Update getting started (#354)

Now uses gwt-maven-archetype and gwt-maven-springboot-archetype, and
has an IntelliJ section.

Co-authored-by: Colin Alworth <[email protected]>

Author: FrankHossfeld

src/main/markdown/doc/latest/tutorial/index.md

@@ -37,7 +37,7 @@ You may also optionally do the following:
 
 ### Build a Sample GWT Application
 
-1.   [Build a Sample GWT Application](gettingstarted.html)
+1.   [Build a Sample GWT Application](gettingstarted-v2.html)
    * Get started with GWT by developing the StockWatcher application from scratch. You'll learn to create a GWT project, build the UI with GWT wigdets and panels, code the client-side functionality in the Java language, debug in development mode, apply CSS styles, compile the Java into JavaScript, and run the application in production mode.
 
 ### Client-Server Communication

src/main/markdown/download.md

@@ -47,7 +47,7 @@ Download
       <a href="versions.html">[Old versions]</a>
     </p>
     <p style='font-size: 90%;'>
-      Next: Go to <a href="gettingstarted.html">Getting Started with the GWT SDK</a>
+      Next: Go to <a href="gettingstarted-v2.html">Getting Started with the GWT SDK</a>
     </p>
   </div>
 </div>
@@ -66,7 +66,7 @@ Download
   <div class='moreinfo'>
     <a class='download-button' href="http://gwt-plugins.github.io/documentation/gwt-eclipse-plugin/Download.html">Download Plugin &amp; SDKs</a>
     <p style='font-size: 90%;'>
-      Next: Go to <a href="usingeclipse.html">Set up Eclipse</a>, then <a href="doc/latest/tutorial/gettingstarted.html">Build a Sample App</a>
+      Next: Go to <a href="usingeclipse.html">Set up Eclipse</a>, then <a href="doc/latest/tutorial/gettingstarted-v2.html">Build a Sample App</a>
     </p>
   </div>
 </div>

src/main/markdown/gettingstarted-v2.md

@@ -0,0 +1,207 @@
+Getting Started
+===
+
+Starting with 2.11.0 of the GWT SDK the [webAppCreator](gettingstarted-outdated.html) is deprecated. Instead, we will use 
+the [gwt-maven-archetypes](https://github.com/tbroyer/gwt-maven-archetypes) by Thomas Broyer to create a new GWT project. Using the **artifactId: modular-webapp** 
+the plugin generates a Maven project with separate modules for
+
+* client
+* server
+* shared.
+
+**Separation of code is the way to go in modern web development.** 
+
+## TOC
+
+*  [Prerequisites](#prereqs)
+*  [Create your first web application](#create)
+*  [Run locally in super dev mode](#run)
+*  [Make a few changes](#change)
+*  [Debugging the browser](#bebug)
+*  [Compile and run in production mode](#compile)
+*  [Set up an IDE](#setup)
+
+## Prerequisites<a id="prereqs"></a>
+
+1.  GWT 2.11.0 still supports Java 8 (running and building). We suggest to use at least Java 11 or 17. If necessary, download and
+    install the Java SE Development Kit (JDK) <a href="https://adoptium.net/de/temurin/releases/" 
+    rel="nofollow">from Eclipse Temurin</a> for your platform. Install the JDK by following the 
+    installation instructions. 
+2.  Apache Maven is also necessary to run the gwt-maven-archetype. In this sample the Maven CLI is used. If
+    you don't already have it, install <a href="https://maven.apache.org/download.cgi" rel="nofollow">Apache Maven</a>.
+
+If you have problems running the gwt-maven-archetype from the command line, try setting the
+$JDK_HOME environment variable with export JDK_HOME="[pathToJDK]" and $MAVEN_HOME environment variable with export MAVEN_HOME="[pathToMaven]"
+and add both to the path. 
+
+## Create your first web application<a id="create"></a>
+
+Open a terminal and choose the directory you like to generate the project into. Generate a new project using: 
+
+```
+mvn archetype:generate \
+   -DarchetypeGroupId=net.ltgt.gwt.archetypes \
+   -DarchetypeVersion=LATEST \
+   -DarchetypeArtifactId=modular-webapp
+```
+
+The archetype will request values for:
+
+* **groupId**: com.mycompany.mywebapp
+* **artifactId**: mywebapp
+* **version**: HEAD-SNAPSHOT
+* **package**: com.mycompany.mywebapp
+* **module-short-name**: mywebap
+
+After entering the parameter above, the terminal shows something like that:
+
+```
+[INFO] Using property: module = App
+Define value for property 'groupId': com.mycompany.mywebapp
+Define value for property 'artifactId': mywebapp
+Define value for property 'version' 1.0-SNAPSHOT: : HEAD-SNAPSHOT     
+Define value for property 'package' com.mycompany.mywebapp: : com.mycompany.mywebapp
+Define value for property 'module-short-name' app: : MyWebApp
+Confirm properties configuration:
+module: App
+groupId: com.mycompany.mywebapp
+artifactId: mywebapp
+version: HEAD-SNAPSHOT
+package: com.mycompany.mywebapp
+module-short-name: mywebapp
+ Y: :         
+```
+
+Enter **Y** to continue.
+
+Now, the new project will be generated and you see the following messages:
+
+```
+[INFO] ----------------------------------------------------------------------------
+[INFO] Using following parameters for creating project from Archetype: modular-webapp:LATEST
+[INFO] ----------------------------------------------------------------------------
+[INFO] Parameter: groupId, Value: com.mycompany.mywebapp
+[INFO] Parameter: artifactId, Value: mywebapp
+[INFO] Parameter: version, Value: HEAD-SNAPSHOT
+[INFO] Parameter: package, Value: com.mycompany.mywebapp
+[INFO] Parameter: packageInPathFormat, Value: com/mycompany/mywebapp
+[INFO] Parameter: package, Value: com.mycompany.mywebapp
+[INFO] Parameter: module-short-name, Value: MyWebApp
+[INFO] Parameter: module, Value: App
+[INFO] Parameter: groupId, Value: com.mycompany.mywebapp
+[INFO] Parameter: artifactId, Value: mywebapp
+[INFO] Parameter: version, Value: HEAD-SNAPSHOT
+[INFO] Parent element not overwritten in /Users/gwt-user/Desktop/mywebapp/mywebapp-client/pom.xml
+[INFO] Parent element not overwritten in /Users/gwt-user/Desktop/mywebapp/mywebapp-shared/pom.xml
+[INFO] Parent element not overwritten in /Users/gwt-user/Desktop/mywebapp/mywebapp-server/pom.xml
+[INFO] Project created from Archetype in dir: /Users/gwt-user/Desktop/mywebapp
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESS
+[INFO] ------------------------------------------------------------------------
+[INFO] Total time:  01:09 min
+[INFO] Finished at: 2023-12-17T17:38:02+01:00
+[INFO] ------------------------------------------------------------------------
+```
+
+Switch to the generated directory by entering `cd mywebapp`.
+
+Listing of the directory (**Windows**: dir, **Mac and Linux**: ls -la), shows: 
+
+```
+drwxr-xr-x@  6 gwt-user  staff   192 Dec 17 17:38 .
+drwx------@ 50 gwt-user  staff  1600 Dec 17 17:38 ..
+drwxr-xr-x@  4 gwt-user  staff   128 Dec 17 17:38 mywebapp-client
+drwxr-xr-x@  4 gwt-user  staff   128 Dec 17 17:38 mywebapp-server
+drwxr-xr-x@  4 gwt-user  staff   128 Dec 17 17:38 mywebapp-shared
+-rw-r--r--@  1 gwt-user  staff  7423 Dec 17 17:38 pom.xml
+```
+
+## Run locally in super dev mode<a id="run"></a>
+
+To start the code server, run the following command:
+
+```
+mvn gwt:codeserver -pl *-client -am
+```
+
+and entering the following command in another terminal window to start the server:
+
+```
+mvn jetty:run -pl *-server -am -Denv=dev
+```
+
+Now, switch to your preferred browser (we suggest using: Chrome, FireFox or Opera) and enter:
+
+```
+http://lcoalhost:8080
+```
+
+Yet, the application is running in super dev mode. You see something like this in the browser:
+
+<div class="screenshot"><a href="images/mywebapp.png"><img src="images/mywebapp.png" alt="Screenshot" width="42%"/></a></div>
+
+## Make a few changes<a id="change"></a>
+
+Let's change the label of the button. Because this is something on the client side, we need to locate the source code in the client module. 
+The source code is located in the `mywebapp-client/src/main/java/com/mycompany/mywebapp` subdirectory and the source in the `App.java` class.
+
+Look inside `App.java`. Line 42 constructs the "Send" button.
+
+```
+final Button sendButton = new Button("Send");
+```
+
+Change the text from "Send" to "Send to Server".
+
+```
+final Button sendButton = new Button("Send to Server");
+```
+
+Save the file and simply click "Refresh" in your browser to see your change. The button should now say "Send to Server" instead of "Send":
+
+## Debugging the browser<a id="debug"></a>
+
+In super dev mode, you can easily debug your client code in the browser. While running your application, open the dev tools 
+in your browser. Select the `Sources`-tab and press `ctrl-P` (Windows/Linux) or `cmd-P` (macOS). A popup opens. Enter `App.java` and press return.
+
+<div class="screenshot"><a href="images/sdm-debugger.png"><img src="images/sdm-debugger.png" alt="Screenshot" width="42%"/></a></div>
+
+The source code of the `App.java` class is displayed in the debugger. Add a breakpoint by clicking of Line number 94. Press the send button.
+The execution will stop at line 94. The stacktrace is visible, the content of the variable, etc. 
+
+<div class="screenshot"><a href="images/sdm-debugger-breakpoint.png"><img src="images/sdm-debugger-breakpoint.png" alt="Screenshot" width="42%"/></a></div>
+
+## Compile and run in production mode<a id="compile"></a>
+
+To run the application as JavaScript in what GWT calls "production mode", create the application by executing:
+
+```
+mvn clean package
+```
+
+The Maven "package" goal invokes the GWT compiler which generates a number of JavaScript and HTML files from the
+MyWebApp Java source code in the `target/` subdirectory.  There you will find a `mywebapp-server-HEAD-SNAPSHOT.war`.
+You can deploy this war file to every servlet engine and run it. Once running, enter `mywebapp-server-HEAD-SNAPSHOT/index.html`
+in your web browser.  The application should look identical to the super dev mode above. You can change the name of the war using
+Maven 'buildname`.
+
+Congratulations! You've created your first web application using GWT.
+Since you've compiled the project, you're now running pure JavaScript and
+HTML that works in Edge, Chrome, Firefox, Safari, and Opera. You could now deploy
+your application to production by serving the HTML and JavaScript files from your servlet engine.
+
+In case you prefer a Spring Boot server, check the 
+[gwt-maven-springboot-archetype](https://github.com/NaluKit/gwt-maven-springboot-archetype) plugin. It creates a
+project in a similar way, but uses Spring Boot instead of Jetty on the server side.
+
+## Set up an IDE<a id="setup"></a>
+
+Now that you've created your first app, you probably want to do something a
+bit more interesting. But first, if you normally work with an IDE you'll want to
+set up your IDE to use the GWT SDK:
+
+[Set up Eclipse](usingeclipse.html)
+
+[Set up IntelliJ](usingintellij.html)
+
+Now, with your sample project set up, head over to [Build a Sample GWT App](doc/latest/tutorial/gettingstarted.html).

src/main/markdown/gettingstarted.md

@@ -1,6 +1,9 @@
 Getting Started
 ===
 
+Note: Starting with GWT 2.11.0 the webAppCreator is deprecated, please see the [new instructions](gettingstarted-v2.html). 
+
+
 *  [Prerequisites](#prereqs)
 *  [Download and Install GWT](#download)
 *  [Create your first web application](#create)
@@ -13,11 +16,11 @@ Getting Started
 
 1.  You will need the Java SDK version 1.8 or later. If necessary, download and
     install the Java SE Development Kit (JDK) <a
-    href="http://www.oracle.com/technetwork/java/javase/downloads/index.html" 
+    href="https://www.oracle.com/technetwork/java/javase/downloads/index.html" 
     rel="nofollow">from Oracle</a> or <a href="https://adoptopenjdk.net/" 
     rel="nofollow">from Adopt OpenJDK</a> for your platform.
 2.  Apache Ant is also necessary to run command line arguments in this sample. If
-    you don't already have it, install <a href="http://ant.apache.org/" rel="nofollow">Apache Ant</a>.
+    you don't already have it, install <a href="https://ant.apache.org/" rel="nofollow">Apache Ant</a>.
 
 If you have problems running Ant on the Mac, try setting the
 $JDK_HOME environment variable with export JDK_HOME="/Library/Java/Home"
@@ -55,7 +58,7 @@ run and use the SDK are located in the extracted directory.
 
 ## Create your first web application<a id="create"></a>
 
-GWT ships with a command line utility called [webAppCreator](https://www.gwtproject.org/doc/latest/RefCommandLineTools.html#webAppCreator) that automatically generates all the files you'll need in order to start a GWT project.  It also generates [Eclipse](http://www.eclipse.org/) project files and launch config files for easy debugging in GWT's development mode.
+GWT ships with a command line utility called [webAppCreator](https://www.gwtproject.org/doc/latest/RefCommandLineTools.html#webAppCreator) that automatically generates all the files you'll need in order to start a GWT project.  It also generates [Eclipse](https://www.eclipse.org/) project files and launch config files for easy debugging in GWT's development mode.
 
 You can create a new demo application in a new MyWebApp directory by running `webAppCreator`:
 
@@ -156,4 +159,4 @@ set up Eclipse to use the GWT SDK:
 [Set up Eclipse](usingeclipse.html)
 
 If you are going to stick with the command line, check out Speed Tracer     and then
-head over to [Build a Sample GWT App](doc/latest/tutorial/gettingstarted.html).
+head over to [Build a Sample GWT App](doc/latest/tutorial/gettingstarted-v2.html).

src/main/markdown/index.md

@@ -45,11 +45,11 @@ GWT (pronounced 'gwit') is the official open source project for GWT releases 2.7
     </tr>
     <tr>
       <td>
-        <a href="gettingstarted.html">
+        <a href="gettingstarted-v2.html">
           <img src="images/learnmore.gif" style="float: left; margin-left: 50px; border: 0;" height="48" width="48" />
         </a>
         <div style="margin-left: 112px; margin-bottom: 10px;">
-          <div style="font-size: 120%; font-weight: bold;"><a href="gettingstarted.html">Get Started</a></div>
+          <div style="font-size: 120%; font-weight: bold;"><a href="gettingstarted-v2.html">Get Started</a></div>
           <div style="padding-top: 5px; line-height: 125%;">
             Walk through the first steps needed to get a web application up and running. From there, work through the fundamentals of GWT development with an in-depth tutorial.<br /><br />
           </div>

src/main/markdown/learnmore-sdk.md

@@ -111,8 +111,8 @@ GWT is free, and all of the [code](https://gwt.googlesource.com/) is available u
 
 ## Ready to get started?
 
-<a href="gettingstarted.html">
+<a href="gettingstarted-v2.html">
   <img src="images/arrow-md.png" style="float: left; margin:10px 10px 0px 0px; border-style:none; width: 80px; height: 80px" />
 </a>
 
-[Download the SDK](gettingstarted.html) and get a simple web application up and running.
+[Download the SDK](gettingstarted-v2.html) and get a simple web application up and running.

src/main/markdown/overview.md

@@ -11,7 +11,7 @@ GWT is a development toolkit for building and optimizing complex browser-based a
 
 The [GWT SDK](learnmore-sdk.html) contains the Java API libraries, compiler, and development server. It lets you write client-side applications in Java and deploy them as JavaScript.
 
-*   [Get Started](gettingstarted.html)
+*   [Get Started](gettingstarted-v2.html)
 *   [Tutorials](doc/latest/tutorial/index.html)
 *   [Developer Guide](doc/latest/DevGuide.html)
 
@@ -49,4 +49,4 @@ When you're ready to deploy, GWT compiles your Java source code into optimized,
 
 ## Ready to get started?
 
-[Download the SDK](gettingstarted.html) and get a simple web application up and running. From there, work through the fundamentals of GWT development with the in-depth [tutorials](doc/latest/tutorial/index.html).
+[Download the SDK](gettingstarted-v2.html) and get a simple web application up and running. From there, work through the fundamentals of GWT development with the in-depth [tutorials](doc/latest/tutorial/index.html).

src/main/markdown/usingintellij.md

@@ -0,0 +1,58 @@
+Using IntelliJ
+===
+
+GWT provides a set of tools that can simply be used with a
+text editor, the command line, and a browser. However, you may also use GWT with your
+favorite IDE. The Idea IntelliJ Ultimate Edition provides a GWT plugin, but the free Idea IntelliJ Community Edition 
+is all you need. IntelliJ provides awesome Maven support, enabling the IDE to read the project classpath, and easily create run configurations for compiling and running a GWT project.
+
+*   [Download IntelliJ](#intellij)
+*   [Import a Web Application](#importing)
+*   [Run locally in Super Dev Mode](#running)
+
+## Download IntelliJ<a id="intellij"></a>
+
+If you do not already have IntelliJ, you may download it from the [IntelliJ Website](https://www.jetbrains.com/idea/download/). 
+
+## Import a Web Application<a id="importing"></a>
+
+To import a Web Application - create with an archetype creator, select **File > New > Project from existing source** 
+from the File menu. Select the root directory of the project you want to import and press `enter`.
+
+A dialog opens:
+
+<div class="screenshot"><a href="images/import-into-intellij.png"><img src="images/import-into-intellij.png" alt="Screenshot" width="42%"/></a></div>
+
+Press `Create`. The import process starts and after a few seconds, the project window appears:
+
+<div class="screenshot"><a href="images/intellij-project.png"><img src="images/intellij-project.png" alt="Screenshot" width="42%"/></a></div>
+
+## Run locally in Super Dev Mode<a id="running"></a>
+
+To improve the development experience, you can set up two run configurations, one for the code server and another for the server.
+
+### Code Server Run Configuration
+
+Press `Edit configuration`, a popup appears. Now press `+` and select `Maven`.  
+
+Enter `gwt:codeserver -pl mywebapp-client -am` in the field under `Run`:
+
+<div class="screenshot"><a href="images/intellij-run-code-server.png"><img src="images/intellij-run-code-server.png" alt="Screenshot" width="42%"/></a></div>
+
+Now you have a run configuration, that starts the code server.
+
+Note: When running the code server from the command line, you need to run `gwt:codeserver -pl *-client -am`. 
+This will not work inside a running configuration. Here you have to use the module name instead of '*'. Inside a run 
+configuration, the command line looks like that: `gwt:codeserver -pl mywebapp-client -am`.
+
+### Server Run Configuration
+
+Press `Edit configuration`, a popup appears. Now press `+` and select `Maven`.
+
+Enter `mvn jetty:run -pl *-server -am -Denv=dev` in the field under run:
+
+<div class="screenshot"><a href="images/intellij-run-server.png"><img src="images/intellij-run-server.png" alt="Screenshot" width="42%"/></a></div>
+
+Now, you have a run configuration, that starts the server.
+
+Note: you have to use the module name instead of '*'.

src/main/resources/main.tpl

@@ -40,7 +40,7 @@
                 <ul>
                     <li class="logo"><a href="/">GWT homepage</a></li>
                     <li><a href="overview.html"><i class="icon_overview"></i>Overview</a></li>
-                    <li class="sep"><a href="gettingstarted.html"><i class="icon_getstarted"></i>Get started</a></li>
+                    <li class="sep"><a href="gettingstarted-v2.html"><i class="icon_getstarted"></i>Get started</a></li>
                     <li><a href="doc/latest/tutorial/index.html" class="active"><i class="icon_tutorials"></i>Tutorials</a></li>
                     <li><a href="doc/latest/DevGuide.html"><i class="icon_doc"></i>Docs</a></li>
                     <li><a href="examples.html"><i class="icon_ressources"></i>Resources</a></li>

src/main/resources/toc.md

@@ -1,7 +1,8 @@
-  - [Get Started](gettingstarted.html)
-      - [Overview](gettingstarted.html 'Getting Started with GWT SDK')
+  - [Get Started](gettingstarted-v2.html)
+      - [Overview](gettingstarted-v2.html 'Getting Started with GWT SDK')
       - [SDK Learn More](learnmore-sdk.html 'Learn more about the GWT SDK')
       - [Configure Eclipse](usingeclipse.html)
+      - [Configure IntelliJ](usingintellij.html)
   - [Tutorials](doc/latest/tutorial/index.html)
       - [Overview](doc/latest/tutorial/index.html)
       - [Build a GWT App.](# 'Create, build and run a GWT application')