Angular 2: Understanding of the Index.html structure and purpose.

Generally, the samples of new web programming languages are enough to understand it, but with Angular 2, the number of files and their interaction is so overwhelming, many of us are getting a bit lost. One thing I recommend is that everyone figure out how it all starts.

It all starts with Index.html

Dealing with IE inadequacies and older browsers.

We start with the “PolyFills”. They handle a bunch of browser inadequacy by being kind of a translator for Angular. You might say they make a browser within a browser. Angular speaks clean nice javascript and browsers all have funky issues. These files contain programs and extensions that all work together to deal with them. You’re going to include them in the index header, call one function, one time later on and you’re done. So, add and forget.

Configuration : Where’s my stuff

We included javascript files like this: < script src=some-file-path >< /script>. Angular loads dynamically, meaning it’s going to use a program to include those files. Imagine if you named each of those script files above and rather than using the script tag, you used a javascript call “include” that would just go get it.

What angular does is bring in the

That file is a list of shortcuts ( the object key is “map”) and a list of packages. So, if you have a module called “MyTools” and it is 40 levels down in the directory tree, when you have a component and you need to include it, instead of

import {MyTools} from {'./app/directory/directory/directory/directory/etc.../mytools.js};

systemjs.config.js, you make a shortcut to the directory and then define the shortcut name for the file. that way you can just have

import {MyTools} from {'myShortcutForMyToolsName'};

Next, there are “packages”. Those are the names of angular JS files that can be imported by name, including the one that is going to define the very first module.

Imagine if you had a couple objects like this:

 paths={'SomePathShortcutName': 'folder/folder/someOtherFolder/maybeTenMore/'  
      /* as many as you want here */ },
 
map={   app:'app',
       '@angular/core': paths.SomePathShortcutName+':@angular/core/bundles/core.umd.js'
       /* as many as you want here */ },
 
packages={
            app: { main: './main.js' }
            /* as many as you want here */ }
 

This is NOT the real structure, but it will help you understand. You’ve got a root path defined to keep things organized. You’ve got maps of 2 things.
1: you’ve got app. notice you don’t have apostrophes around app. That tells it that it’s a package and it needs to go find app in the packages, Angular is going to include that, just like you’d include as a regular < script src=whatever > statement in html. Second, you’ve got a name ‘@angular/core’ : ‘yourpathname:the file path to the actual js file‘.

That means that later on if you want to include @angular/core functions and classes, you don’t need to go track it down. Angular will just get it from wherever you say it is here.

It is really really simple when you think about it. It’s just shortcuts to files. Either files to run right away(packages) or files to reference later on(map). Generally, you’ve got ONE package that runs

Remember, that little code script is just to help you understand how it works. the real structure is further down.

So far: 1. Deal with old browsers, 2. tell angular where all your JS files are, 3. tell angular to include some packages right off the bat.

Now, you’ve got the get-go:

So Angular is “System” and you’re tell it to go ahead and include main.js, which was the “app” package in systemjs.config.ts.

As soon as it includes it, it’s going to run whatever code is in that main.js.

Ok, not do difficult yet: Old Browser crap, where are my files, and turn it on. A bit convoluted to understand if you’re not used to this sort of thing, but it should begin to make sense.

Now we need 1 more thing on the index header.

In the header, we need to add a base tag so the angular engine knows where it is. Here’s one if your index file is at the root.

(If you aren’t doing any routing, you don’t need this, but who really does a website with only a single view.)

Angular reads all the html tags, and it uses the base tag to figure out where the app is and all the routing won’t work unless you have that.

Ok, now you’ve got the index and how it works :

1. Deal with old browsers
2. Where are my files
3. Start up my system
4. where is the root of the website

---

So, we’ve got that far, but there are a few other things happening here.

One big key is what happens with that first “System.import(“app”). So, in that systemjs.config.ts file, the one that defines shortcuts and packages, you look under “app” and check out what js file is listed there. I always call mine “main.js”.
Here’s what that section of systemjs.config.ts looks like:

 packages: {
            app: {
                main: './main.js',
                defaultExtension: 'js'
            },
            rxjs: {
                defaultExtension: 'js'
            },
            'angular-in-memory-web-api': {
                main: './index.js',
                defaultExtension: 'js'
            }

Note that first one: “app”. That’s just a shortcut definition to the file, which has your startup component in it

So we look at main.js. You have 2 things here. seriously, that’s it. You’re not supposed to put other stuff here.

import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { AppModule } from './app.module';
const platform = platformBrowserDynamic();
platform.bootstrapModule(AppModule);

So, we start this platformBrowserDynamic() program that is kind of like a holder for Angular 2 that says it is going to operate all its code through a little translator that will fix stuff to make it work in whatever browser opens it up.

Then, we tell that to start a the component we imported up top – which I named “AppModule”.

Ok, so systemjs.config tells me where this main.js is and starts it up.
main.js tells angular to import a component called AppModule from a file called app.module.js (the .js is assumed by Angular)

The Body

Now…. that all is happening in the HEAD. Here’s the body of the index page:

In the body, we have the parent component. Generally people call this app.component.ts. All it is (generally) is a place where you’ll put all your other stuff. I always call that component “my-app”.

Yep… that’s it. Once angular is loaded, it is going to dig through the entire site and read every single html tag looking for custom tags that match any components you’ve written.

The Breakdown

The index page is a very basic set of things you absolutely MUST have to run Angular 2. The entire kickoff starts in the HEAD of the index page and then the magic begins with the first component in the body.

1. Deal with old browsers (polyfill modules are linked in the index head, then called later in main.js)
2. Where are my files? (map the directories – generally node_modules – and tell angular where the bootstrap file is)
3. Start up my system (System.import(the name of the package defined in systemjs packages, brings whatever javascript file is defined there – normally main.js)
4. where is the root of the website (we always have routing, so we need a < base href='my root path‘ / >
5. enter the selector name of the component you “bootstrapped” in main.js.

---