Getting-started.md

Getting Started

Welcome to Reference Implementation, the new Content Delivery web application! This tutorial will take you through creating a custom application from scratch. We assume you are familiar with TypeScript, JavaScript (ES6), Webpack, HTML, XML, React, LESS, CSS, Java, Spring, DXA and Maven.

Some learning material:

1. JavaScript (ES6)
2. TypeScript Getting Started
3. TypeScript Tutorial
4. React Fundamentals
5. React Hello World
6. LESS
7. Webpack
8. Webpack Course
9. Serving Web Content with Spring MVC
10. Maven Getting Started Guide
11. Getting started with DXA 1.7
12. Developing on DXA Java

Software requirements

Make sure you have installed:

• Node.js
  • 64 bit version is recommended
  • Install NodeJs v6.x or higher
• Maven 3
• Tomcat 8.5
• An IDE which has support for TypeScript / LESS
  • Atom
  • Sublime Text
  • Visual Studio Code
  • ...
• An IDE which has support for Java
  • IntelliJ IDEA
  • ...
• A Content Delivery environment with data

In the following guide we're using IntelliJ IDEA Ultimate (for Java) and Visual Studio Code (for LESS / TypeScript / JavaScript).

You can find the result of this guide here

Setting up Maven

In order to download some snaphot artifacts which are used by the archetype. We will need to add a reference to the sonatype snaphots repository.

1. Open up your main settings.xml file. On an Windows machine this file is located at C:\Users\<username>\.m2\settings.xml, on a Linux Ubuntu it is at /usr/share/maven/conf/settings.xml.
2. Add an extra profile inside the profiles section (see code snippet below)
3. Make this the active profile (see code snippet below)

<settings>
    <profiles>
        <profile>
            <id>sonatype-nexus-snapshots</id>
            <repositories>
                <repository>
                    <id>sonatype-nexus-snapshots</id>
                    <name>sonatype-nexus-snapshots</name>
                    <url>https://oss.sonatype.org/content/repositories/snapshots</url>
                    <releases>
                        <enabled>false</enabled>
                    </releases>
                    <snapshots>
                        <enabled>true</enabled>
                    </snapshots>
                </repository>
            </repositories>
        </profile>
    </profiles>
    <activeProfiles>
        <activeProfile>sonatype-nexus-snapshots</activeProfile>
    </activeProfiles>
</settings>

Create a new project using the Maven Archetype

First step you will need to do is to create a new directory. We've created the following directory on our machine: D:\github\dd-webapp-custom-examples. We'll be usign this directory further on in the examples.

Ok Let's start by opening the command prompt and run:

cd "D:\github\dd-webapp-custom-examples"
mvn archetype:generate "-DarchetypeArtifactId=dd-webapp-archetype" "-DarchetypeGroupId=com.sdl.delivery.ish" "-DarchetypeVersion=1.2.0"

Notice that we are using version 1.2.0, this is just an example. We advise you to use the latest available version. We'll pick org.company as our group ID and custom-webapp as the name of our artifact ID.

[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building Maven Stub Project (No POM) 1
[INFO] ------------------------------------------------------------------------
[INFO]
[INFO] >>> maven-archetype-plugin:3.0.1:generate (default-cli) > generate-sources @ standalone-pom >>>
[INFO]
[INFO] <<< maven-archetype-plugin:3.0.1:generate (default-cli) < generate-sources @ standalone-pom <<<
[INFO]
[INFO] --- maven-archetype-plugin:3.0.1:generate (default-cli) @ standalone-pom ---
[INFO] Generating project in Interactive mode
[INFO] Archetype repository not defined. Using the one from [com.sdl.delivery.ish:dd-webapp-archetype:1.2.0] found in catalog remote
Define value for property 'groupId': org.company
Define value for property 'artifactId': custom-webapp
Define value for property 'version' 1.0-SNAPSHOT: :
Define value for property 'package' org.company: :
Confirm properties configuration:
groupId: org.company
artifactId: custom-webapp
version: 1.0-SNAPSHOT
package: org.company
 Y: : y

Building the project

To buid the project, run the following command from the command line:

cd "D:\github\dd-webapp-custom-examples\custom-webapp"
mvn clean install

Setting up IntelliJ IDEA development environment

Next step, we set up IntelliJ IDEA for development:

1. Launch IntelliJ
2. Open the directory where you've created the archetype, in our case this is the D:\github\dd-webapp-custom-examples\custom-webapp directory

Setting up Content Delivery configuration

First step is to add the necessary configuration inside the cd_client_config.xml file, located at src/main/resources/cd_client_conf.xml. We need to provide the location of the discovery service, the client ID and the client secret of the Content Delivery system we are using.

Setting up Tomcat

We'll describe this for usage with the IntelliJ Ultimate Edition and the IntelliJ Community Edition (free). You can find a comparison of both versions here.

After this you are ready to start customizing the application.

IntelliJ Community Edition

There is no tight integration with Tomcat and IntelliJ Community Edition, therefore some manual actions are required.

Install Tomcat plugin:

1. Download Tomcat runner plugin for IntelliJ
2. Extract zip file inside plugins directory of IntelliJ installation (eg C:\Program Files\JetBrains\IntelliJ IDEA Community Edition 2017.1.2\plugins)
3. Restart IntelliJ

Start debugging:

1. Start IntelliJ as an Administrator
2. Select the Run item in the top menu
3. Open Edit Configurations
4. Select the + icon on the top left
5. Select Tomcat Runner

6. Define a name for the configuration, we're using Tomcat
7. Set path to Tomcat Location
8. Add a context, we'll be using /web-app as path and D:\github\dd-webapp-custom-examples\custom-webapp\target\custom-webapp-1.0-SNAPSHOT as the Document Base.
9. Add a new Maven goal
10. Fill in clean install inside the command line field

11. Close the dialog by clicking the Ok button
12. Start the custom web application by selecting Run -> Debug 'Tomcat'

IntelliJ Ultimate Edition

If you have the paid version of IntelliJ there is already a Tomcat integration.

In order to debug it we'll setup a configuration for Tomcat.

1. Select the Run item in the top menu
2. Open Edit Configurations
3. Select the + icon on the top left
4. Go to Tomcat Server and select Local

5. Define a name for the configuration, we're using Tomcat
6. Remove all task from the list at the bottom of the dialog
7. Add a new Maven goal

8. Fill in clean install inside the command line field

9. Select Ok

10. Open the deployment tab

11. Select the + icon next to the Deploy at server startup list

12. Select the exploded war file
13. Close the dialog by selecting the Ok button

14. Start the custom web application by selecting Run -> Debug 'Tomcat'