Speak Friend and Enter - The Journey Through Mordor to create your first Speak 3 Application

Dain and Diana are currently learning all about Sitecore Speak 3. As they know nothing about NodeJS or Angular this is quite a challenge for them.  This article will help you with some of the obstacles they ran into and how you can overcome them.

A few friends have helped Dain in his quest. Special thanks to:

• Tim AKA "Hi My Name Is Tim" for writing an amazing article on Creating a Sitecore Speak 3 application
• Dean Thrasher please follow him on Twitter using @dthrasher. His team created a Speak 3 app as part of Hackathon and that helped us with some of the issues
• Tony Mamedbekov my hackathon team mate that taught me lots about npm and versions of packages in the packages.json file. Dll hell all over again :)
• Julia Gavrilova who wrote another amazing article that ensured I knew that I needed Angular 4 not 5. Thanks you saved me a lot of time.
• James Q Quick please follow him on Twitter using @jamesqquick. I used his article to help me start debugging my Speak 3 app.  

Ok let's get started.

Step 1: Get Prepared First.

As the BoyScouts say, always be prepared. Before we start we need to get things ready.

• As Tim recommends you should install Visual Studio Code. DAIN and Diana recommend it as well.
• Install Node.JS. I just installed the Recommended for most users version.
• Install Angular 4 using
  
  Npm install -g @angular/cli@1.4
  
  Beware this is one of those gotchas. Thanks Julia Gavrilova for this tip. I could not figure out why I got the error "Error: Cannot find module 'webpack/lib/node/NodeTemplatePlugin'" and then I read your blog and realized

  Sitecore Speak 3 uses Angular 4, which means that all modules you decide to use should support this version of Angular. In addition to that syntax is different between Angular versions, and you need to pay attention to that as well when writing your code. 

  If you previously installed Angular 5 or 6 instead and you run the command it will roll back and reinstall the proper version.
• As a sanity check you should check the versions. In my case my global Angular CLI version (7.3.6) is greater than my local version (1.2.7).
  
   ng version
• If your local version is not new enough you will need to do an uninstall in reinstall of the right one.

Step 2: Creating your application

• Open a Command Prompt as Run As Administrator. 
• Change directory to the folder above where you want to create your application and then run this replacing app-name with the name of your application eg. DainSpeak3
  
  ng new app-name
• Now you can stumble through or you can take Tim's advice and download the Sitecore Speak 3 Reference Application. I did and it saved me a lot of time. Thanks Tim
• Once downloaded look in the "Sitecore SPEAK 3.0 Reference Application\SPEAK3.Apps.Minimal\SPEAK3.Apps.Minimal\code\Sc.Integration.Ref.App.Client" folder. Copy the .npmrc and package.json file from here to your application folder.
• Change directory so you are in your application folder and run
  
  npm install
• Now if the versions are not right when you run ng version then you may have to do a few npm uninstall and npm install of given components to get all the right ones.
• If you try ng server --open from your application folder and it does not load it will often tell you which package it could not load.  If it says config is null or some obscure error then do an npm uninstall and npm install and it should tell you which modules it skipped. Hopefully at some point they will solve this issue with package versions.  Until then you have to play with it.

After running ng server --open I got my application to open on the default port.  It is showing the Welcome to app screen but that is the start. If you got here pat yourself on the back and go buy a poutine and a chocolate milk or if you prefer a nice glass of Jura Scotch.

Now you may be all excited because it opened but remember if you wanted it to be disconnected mode then you need to load it a little differently.

npm run-script start:disconnected

Step 3: Customizing How Your Application Starts

So the default port for your application is 4200 but you don't have to live with that. You can open the 

angular-cli.json and change the port to whatever you wish. The default file will be missing the serve section so you will need to add it so it looks like below.  For those Stephen King fans you will understand the port number.

  "defaults": {

    "styleExt": "css",

    "component": {},

     "serve": {

          "port": 1408

     }

Once you change the port you can open your application again and it will use the new port.

Step 4: Paging Dr Kildare or customizing how your application looks

This is where the real fun begins. Open Visual Studio Code and then from the File menu chooose Open Folder.  Choose your application folder and click Select Folder.  This will open your application.

To start we will look at the app.component.html file located in the /src/apps folder. I simply copied the one from the reference application.

Next you can generated a new landing-page component using ng generate component landing-page

I took the easy way out and copied the \src\app folder from the reference project. If you want to look at the steps to do it yourself you can see them in the article Speak 3 adventures of a back end developer.

Open the angular-cli.json and look for the style section. Change style.css to ../node_modules/@speak/styling/dist/styles/sitecore.css

The style node now looks like this:

      "styles": [
        "../node_modules/@speak/styling/dist/styles/sitecore.css"
      ],

Again you can follow the steps in in the article Speak 3 adventures of a back end developer or you can simply copy over the angular-cli.json from the reference project. I took the short cut and copied it over.

If you choose to copy it like I did then you only have to change the project name to match yours and the port to match yours.

Step 5: Debugging With Visual Studio Code

Speaking of Scotch, this will be a lifesaver especially if you are new to Angular and Speak3.  Check out this article and it will show you step by step how to create a debugging configuration.

https://scotch.io/tutorials/debugging-angular-cli-applications-in-visual-studio-code

Step 6: Simulating Login and Logout while Disconnected

This is done by copying the mock folder in the root of the reference application to your application.

Step 7: Running it inside Sitecore

The first step is creating your Application in Sitecore. Log into the Sitecore admin and click on Desktop. Change the database to core and then open content editor.  Navigate to /sitecore/content/applications. Right-click and create your application.

The second step is to prepare to build your release.

If you copied the packages.json file from Sitecore you will need to edit the application name and version. Under scripts you will need to edit the build property to point to your application.

{
  "name": "MySpeak",
  "version": "0.0.1",
  "license": "MIT",
  "scripts": {
    "ng": "ng",
    "start": "npm run start:disconnected",
    "start:disconnected": "ng serve --proxy-config disconnected-mode.conf.js",
    "build": "ng build --prod --base-href=/sitecore/shell/client/Applications/MySpeak",
    "postbuild": "ng-sc --entry ./dist/index.html && sc-license-checker",
    "test": "ng test",
    "lint": "ng lint",
    "e2e": "ng e2e"
  },

If your application uses any more modules the you would need to add them here too. Once you are ready run this command to create your release application in the dist folder.

npm run-script build

To be Continued ...