cli-quickstart.jade

include _util-fns
  
:marked
  Good tools make application development quicker and easier to maintain than
  if we did everything by hand.
  
  The [**Angular-CLI**](https://cli.angular.io/) is a **_command line interface_** tool
  that can create a project, add files, and perform a variety of on-going development tasks such 
  as testing, bundling, and deployment.
  
  Our goal in this CLI QuickStart chapter is to build and run a super-simple Angular 
  application in TypeScript, using Angular-CLI 
  while adhering to the [Style Guide](./guide/style-guide.html) recommendations that
  benefit _every_ Angular project.
  
  By the end of the chapter, we'll have a basic understanding of development with the CLI
  and a foundation for both these documentation samples and our real world applications.

  We'll pursue these ends in the following high-level steps:
  
  1. [Set up](#devenv) the development environment
  2. [Create](#create-proj) a new project and skeleton application
  3. [Serve](#serve) the application
  4. [Edit](#first-component) the application


.l-main-section
h2#devenv Step 1. Set up the Development Environment
:marked
  We need to set up our development environment before we can do anything.
   
  Install **[Node.js® and npm](https://nodejs.org/en/download/)**
  if they are not already on your machine.
.l-sub-section
  :marked
    **Verify that you are running node `v4.x.x` and npm `3.x.x`**
    by running `node -v` and `npm -v` in a terminal/console window.
    Older versions produce errors.
:marked
  Then **install the [Angular-CLI](https://github.com/angular/angular-cli)** globally.
  
code-example(format="").
  npm install -g angular-cli
  
.l-main-section
h2#create-project Step 2. Create a new project
:marked
  Open a terminal window.
  
.alert.is-important
  :marked
    _Windows Developers_: open a console window _as an **administrator**_.
    The Angular-CLI build steps later in this tutorial 
    create <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/aa365680(v=vs.85).aspx" target="_blank"><i>symbolic links</i></a> 
    to various directories. These so-called _symlinks_ save time and space.
    But it takes administrator rights under Windows to create them.

:marked
  Generate a new project and skeleton application by running the following commands:

code-example(format="").
  ng new cli-quickstart

.l-sub-section
  :marked
    Patience please. 
    It takes time to set up a new project, most of it spent installing npm packages.

.l-main-section
h2#serve Step 3: Serve the application
:marked
  Go to the project directory and launch the server.
code-example(format="").
  cd cli-quickstart
  ng serve
:marked
  The `ng serve` command launches the server, watches our files, 
  and rebuilds the app as we make changes to the files.
  
  Open a browser on `http://localhost:4200/`; the app greets us with a message:
  
figure.image-display
  img(src='/resources/images/devguide/cli-quickstart/app-works.png' alt="Our app works!")

.l-main-section
h2#first-component Step 4: Edit our first Angular component
:marked
  The CLI created our first Angular component for us. 
  This is the _root component_ and it is named after the project. We created the project
  with the name `cli-quickstart` so our component is `CliQuickstartAppComponent` and 
  it's in the file `/src/app/cli-quickstart.component.ts`
.l-sub-section
  :marked
    _CliQuickstartAppComponent_ is a _horrible name_. Almost everyone renames it to _AppComponent_ ...
    and renames all of the associated files to _app.component.??_ as we do throughout the documentation.
    We'll leave that step as an exercise.

:marked
  Open the component file and change the `title` property from _cli-quickstart works!_ to _My First Angular App_:
  
+makeExample('cli-quickstart/ts/src/app/cli-quickstart.component.ts', 'title', 'src/app/cli-quickstart.component.ts')(format=".")

:marked
  The browser reloads automatically and we see the revised title. That's nice, but we can make it look better.
  
  Open `src/app/cli-quickstart.component.css` and give our component some style 

+makeExample('cli-quickstart/ts/src/app/cli-quickstart.component.css', null, 'src/app/cli-quickstart.component.css')(format=".")

figure.image-display
  img(src='/resources/images/devguide/cli-quickstart/hello-angular.png' alt="Output of QuickStart app")  
  
:marked
  Looking good!

.l-main-section
:marked
  ## What's next?
  Our first application doesn't do much. It's basically "Hello, World" for Angular.

  We kept it simple in our first pass: we wrote our first Angular application using the angular CLI
  and modified our first component. That's about all we'd expect to do for a "Hello, World" app.

  **We have greater ambitions!**
:marked
  We're about to take the next step and build a small application that
  demonstrates the great things we can build with Angular.

  Join us on the [Tour of Heroes Tutorial](./tutorial)!

  Or stick around a bit longer to learn a few things about what we just did.
<br><br>
.l-main-section
h1#behind-the-code Behind the code
:marked
  ### CliQuickstartAppComponent is the root of the application

  Every Angular app has at least one **root component**, that hosts the client user experience.
  Components are the basic building blocks of Angular applications.
  A component controls a portion of the screen &mdash; a *view* &mdash; through its associated template.

  This QuickStart has only one, extremely simple component.
  But it has the essential structure of every component we'll ever write:

  * one or more [import](#component-import)
  statements to reference the things we need.
  * a [@Component decorator](#component-decorator)
  that tells Angular what template to use and how to create the component.
  * a [component class](#component-class)
  that controls the appearance and behavior of a view through its template.

a#component-import
:marked
  ### Import

  Angular apps are modular. They consist of many files, each dedicated to a purpose.

  Angular itself is modular. It is a collection of library modules
  consisting of several, related features that we'll use to build our application.

  When we need something from a module or library, we import it.
  Here we import the `Component` decorator from the Angular **_core_** library 
  that we'll use as a decorator (`@Component`) to attach metadata to our component class.
  .

+makeExcerpt('src/app/cli-quickstart.component.ts', 'import')

h3#component-decorator @Component decorator
:marked
  `Component` is a *decorator* function that associates Angular *metadata* with a
  component class.
  The metadata tell Angular how to create and display instances of this component.

  We apply this function to the component class by prefixing the function name with the
  **@** symbol and invoking it with a metadata object, just above the class.

+makeExcerpt('src/app/cli-quickstart.component.ts', 'metadata')

:marked
  This particular metadata object has four fields, a `moduleId`, a `selector` a `templateUrl` and an array of `styleUrls`.
  
  The **moduleId** specifies the location of _this_ component definition file
  so that Angular can find the corresponding _template_ and _style_ files with URLs that
  are relative to this component file. 
  The module loader sets the value of `module.id` at runtime;
  we're using that value to set the metadata `moduleId` property.

  The **selector** is a [CSS selector](https://developer.mozilla.org/en-US/docs/Web/Guide/CSS/Getting_Started/Selectors) 
  identifying the HTML element that represents this component.

  The element tag name for this component is `cli-quickstart-app`.
  Angular creates and displays an instance of our `CliQuickstartAppComponent`
  wherever it encounters a `<cli-quickstart-app>` element in the host HTML.

  The **templateUrl** locates the component's companion template HTML file.
  The template tells Angular how to render this component's view.
  
  Our template is a single `<h1>` element surrounding some peculiar Angular data binding syntax.
+makeExample('src/app/cli-quickstart.component.html', null, 'src/app/cli-quickstart.component.html')(format='.')
:marked
  The `{{title}}` is an _interpolation_ binding that causes Angular to display the component's
  `title` property. After out edit, Angular displays "Hello Angular".
  We'll learn more about data binding as we read through the documentation.
  
  The **styleUrls** array specifies the location(s) of the component's private CSS style file(s).
  The CLI generated an empty file for us and we added styles to it.

:marked
  ### Component class
  At the bottom of the component definition file is the component class named `CliQuickstartAppComponent`.
+makeExcerpt('cli-quickstart/ts/src/app/cli-quickstart.component.ts', 'class')
:marked
  This class contains the `title` property that we're displaying in our template.
  We can expand this class with more properties and application logic.

  We **export** `CliQuickstartAppComponent` so that we can **import** it elsewhere in our application ... as we're about to do.

:marked
  ### The *main.ts* file
  
  How does Angular know what to do with our component?  We have to tell it. 
  We _bootstrap_ our application in the file `main.ts`.
  
+makeExcerpt('src/main.ts', 'important')

:marked
  We import the two things we need to launch the application:

  1. Angular's browser `bootstrap` function
  1. The application root component, `CliQuickstartAppComponent`.

  Then we call `bootstrap` with `CliQuickstartAppComponent`.

  ### Bootstrapping is platform-specific
  Notice that we import the `bootstrap` function from `@angular/platform-browser-dynamic`,
  not `@angular/core`.
  Bootstrapping isn't core because there isn't a single way to bootstrap the app.
  True, most applications that run in a browser call the bootstrap function from
  this library.

  But it is possible to load a component in a different environment.
  We might load it on a mobile device with [Apache Cordova](https://cordova.apache.org/) or [NativeScript](https://www.nativescript.org/).
  We might wish to render the first page of our application on the server
  to improve launch performance or facilitate
  [SEO](http://www.google.com/webmasters/docs/search-engine-optimization-starter-guide.pdf).
  These targets require a different kind of bootstrap function that we'd import from a different library.

  ### Why create a *main.ts* file?

  Both `main.ts` and the application component files are tiny.
  This is just a QuickStart.
  We could have merged these two files into one
  and spared ourselves some complexity.

  We'd rather demonstrate the proper way to structure an Angular application.
  App bootstrapping is a separate concern from presenting a view.
  Mixing concerns creates difficulties down the road.
  We might launch the `CliQuickstartAppComponent` in multiple environments with different bootstrappers.
  Testing the component is much easier if it doesn't also try to run the entire application.
  Let's make the small extra effort to do it *the right way*.
  
  ### Loading the application with SystemJS
  
  The CLI uses `System.js` to load the application. We just need to call `System.import` and pass it our `main.ts`
  file to boot our application.
  
+makeExcerpt('src/index.html', 'import')

:marked
  ### Displaying the root component 
  
  When Angular calls the `bootstrap` function in `main.ts`, it reads the `CliQuickstartAppComponent`
  metadata, finds the `cli-quickstart-app` selector, locates an element tag named `cli-quickstart-app`
  in the `<body>` tag of the `index.html`, and renders our application's view between those tags.
+makeExcerpt('src/index.html', 'body')
:marked
  This is just a taste of Angular develoment. There's much more to learn. Now really is the time to
  head over to the [Tour of Heroes Tutorial](./tutorial)!