angular-cn/public/docs/js/latest/quickstart.jade

include ../../../_includes/_util-fns

:markdown
  Let's start from zero and build a simple Angular 2 application in JavaScript.

.callout.is-helpful
  header Don't want JavaScript?
  :markdown
    Although we're getting started in JavaScript, you can also write Angular 2 apps
    in TypeScript and Dart by selecting either of those languages from the combo-box in the banner.

:markdown
  We'll do it in six short steps
  1. Create a project folder
  1. Install essential libraries
  1. Write the root component for our application in *app.js*
  1. Bootstrap the app  
  1. Create an *index.html*
  1. Run it

.l-main-section
  :markdown
    ## Create a project folder
    
    **Create a new folder** to hold our application project, perhaps like this:
    ```
    mkdir angular2-quickstart
    cd    angular2-quickstart
    ```
.l-main-section
  :markdown
    ## Install essential libraries

    We'll use the **npm package manager** to install packages for
    the libraries and development tools we need: 

    >angular2 - the Angular 2 library.
    
    >[live-server](https://www.npmjs.com/package/live-server "Live-server") 
    a static file server that reloads the browser when files change.
    
    We could reference the libraries on the web or download them to our project. 
    That isn't a sustainable development process and package loading with npm is really
    easy once we have it installed.

  .alert.is-helpful 
    :markdown
      Don't have npm? [Get it now](https://docs.npmjs.com/getting-started/installing-node "Installing Node.js and updating npm")
      because we're going to use it now and repeatedly throughout this documentation.
 
  :markdown
    **Open** a terminal window and enter these commands:
    ```
    npm init -y
    npm i angular2@2.0.0-alpha.44 --save --save-exact
    npm i live-server --save-dev
    ```
    These commands both *install* the packages and *create* an npm configuration
    file named `package.json`.
    The essence of our `package.json` should look like this:

  +makeJson('quickstart/js/package.json', { paths: 'name, version, dependencies, devDependencies'})

  :markdown
    There is also a `scripts` section. **Find and replace** it with the following:

  +makeJson('quickstart/js/package.json', { paths: 'scripts'})

  :markdown
    We've just extended our project world with a script command that we'll be running very soon.

.l-main-section
  :markdown
    ##  Our first Angular component

    Add a new file called *app.js* and paste the following lines:

  +makeExample('quickstart/js/app.js', 'class-w-annotations')

  :markdown
    We're creating a visual component named **`AppComponent`** by chaining the 
    `Component` and `Class` methods that belong to the **global Angular namespace, `ng`**.

    ```
    var AppComponent = ng
        .Component({...})
        .Class({...})
    ```
    The **`Component`** method takes a configuration object with two
    properties. The `selector` property tells Angular that this is a component
    controlling a host element named "my-app". 
    Angular creates and displays an instance of our `AppComponent`
    wherever it encounters a `my-app` element.
    
    The `template` property defines the visual appearance of the component.
    We're writing the HTML template inline in this example. 
    Later we'll move the HTML to a view template file and
    assign the template's filename to the `templateUrl` property.
    We'll prefer that practice for all but the most trivial templates.

    The **`Class`** method is where we implement the component itself,
    giving it properties and methods that bind to the view and whatever
    behavior is appropriate for this part of the UI.
    
    This component class has the bare minimum implementation:
    a *no-op* constructor function that does nothing because there is nothing to do.
    We'll see more interesting component classes in future examples.
    
.l-main-section
  :markdown
    ## Bootstrap the app
    We need to do something to put our application in motion.
    Add the following to the bottom of the `app.js` file:
    
  +makeExample('quickstart/js/app.js', 'bootstrap')

  :markdown
    We'll wait for the browser to tell us that it has finished loading
    all content and then we'll call the Angular `bootstrap` method.
    
    The `bootstrap` method tells Angular to start the application with our 
    `AppComponent` at the application root.
    We'd be correct to guess that someday our application will
    consist of more components arising in tree-like fashion from this root.

    ### Wrapped in an IIFE
    We don't want to pollute the global namespace.
    We don't need an application namespace yet.
    So we'll surround the code in a simple IIFE 
    ("Immediately Invoked Function Execution") 
    wrapper.
    
    Here is the entire file:
  +makeExample('quickstart/js/app.js', 'dsl')
    
.l-main-section
  :markdown
    ## Create an *index.html*

    **Add a new `index.html`** file to the project folder and enter the following HTML

  +makeExample('quickstart/js/index.html', null, 'index.html')(format="")
  .l-sub-section
    :markdown
      Our app loads two script files in the `<head>` element:

      >***angular2.sfx.dev.js***, the Angular 2 development library that puts
      Angular in the global `ng` namespace.

      >***app.js***, the application JavaScript we just wrote.

      In the `<body>`, there's an element called `<my-app>`. 
      This is the placeholder for the *root* of the
      application. Angular displays our application here.

.l-main-section
  :markdown
    ## Run it!

    We need a file server to serve the static assets of our application 
    (*index.html* and *app.js*).

    For this example we'll use the **live-server** that we installed with `npm`
    because it performs a live reload by default and it's
    fun to watch the browser update as we make changes.

    Open a terminal (or Windows/Linux command line) and enter:

  pre.prettyprint.lang-bash
    code npm start

  .alert.is-helpful
    :markdown
       That's the `npm` command we added earlier to the `scripts` section of `package.json`
      
  :markdown
    **live-server** loads the browser for us and refreshes the page as we make
    changes to the application.
    
    In a few moments, a browser tab should open and display

  figure.image-display
    img(src='/resources/images/devguide/quickstart/my-first-app.png' alt="Output of quickstart app")

  :markdown
    ### Make some changes
    The `live-server` detects changes to our files and refreshes the browser page for us automatically.

    Try changing the message to "My SECOND Angular 2 app". 
    The `live-server` sees that change and reloads the browser.

    Keep `live-server` running in this terminal window and keep trying changes. 
    You can stop it anytime with `Ctrl-C`.
    
    **Congratulations!  We are in business** ... and ready to take
    our app to the next level.