Awesome

aurelia-axel-northwind

As a user, I want a walk through of creating a web app from the aurelia-axel starter kit, based of a familiar database (Northwind).

Setup Your Environment

SQL Server

Install SQL Server (Express)
Download Northwind Database Backup
Restore Northwind Database 4. Copy the downloaded Northwind backup to the SQL Server Backup folder (something like C:\Program Files\Microsoft SQL Server\MSSQL13.SQLEXPRESS\MSSQL\Backup) 5. Restore the backup (from SQL Server Management Studio, right click databases --> restore)
```
 ![image](https://cloud.githubusercontent.com/assets/10272832/14064851/bdc05b76-f3cf-11e5-9e41-b8b3c323f6e9.png)
```

Now you should have the Northwind database available.

Prepare Visual Studio

If you don't alerady have it, grab yourself a copy of Visual Studio - (free) Community Edition

Install Task Runner Explorer

We are going to be using gulp for various build steps (which will be tasks in a gulpfile.js). It is very convenient to be able to run these tasks from within Visual Studio.

Luckily, the brilliant Mads Kristensen is on the case and has provided (a separately installed) Task Runner Explorer which can display and run gulp tasks from within Visual Studio.

You'll need Visual Studio for developing the server-side code. This is only one path for server-side code, of course.

Once you have Task Runner Explorer installed, you can view it by choosing View --> Other Windows --> Task Runner Explorer:

You will see something that looks like this:

Install Web Essentials

Web Essentials (make sure you're getting the latest version).

Install Web Compiler

Web Compiler

Generating Docs

TypeScript Docs

To generate the TypeScript Docs, bring up Task Runner Explorer, right click the typedoc task, and click run:

If you want to inspect (or change) the typedoc config, look at gulpfile.js:

The the generated docs include a main page that comes from docs.md, which is a markdown formatted document and can be edited as desired to provide doc content.

var gulp = require("gulp");
var typedoc = require("gulp-typedoc");

gulp.task("typedoc", function () {
    return gulp
		.src(["views/**/*.ts", "typings/**/*.ts"])
		.pipe(typedoc({
		    // TypeScript options (see typescript docs) 
		    module: "amd",
		    target: "es5",
            experimentalDecorators: true,
            includeDeclarations: true,
            readme: "docs.md",

		    // Output options (see typedoc docs) 
		    out: "./docs",
		    json: "docs.json",

		    // TypeDoc options (see typedoc docs) 
		    name: "aurelia-axel-northwind",
		    ignoreCompilerErrors: false,
		    version: true
		}))
    ;
});

Get Started With Data

Copy aurelia-axel

Rename the folder: aurelia-axel :arrow_right: aurelia-axel-northwind
Rename the solution file :arrow_right: aurelia-axel-northwind.sln
Switch to the aurelia-axel-northwind folder
Rename the project file :arrow_right: aurelia-axel-northwind.csproj
Switch back to the main folder
Open the solution in Visual Studio (run as administrator)
Right click the old project (which didn't load) and remove it from the solution.
Right click the solution and add - existing project and browse to the renamed project file
The project should load

Create EF Model

Create new empty project
Delete the (unhelpful) Class1.cs
Add Entity Framework Model
Bask in the glory of your automatically created EF model !! :smile:

Create OData Controller

Make sure you did a rebuild on the solution
Add a reference to the EF project
Add the connection string from the EF project's app.config to the web project's web.config
Add the OData controller
Copy the using statements to the WebApiConfig.cs file
Copy the OData code block to the WebApiConfig.cs file
Increase the Customer OData Controller's expand depth to 4 (from the default 2)
Rebuild and run in the browser

Play with OData URLs

The `/odata` URL returns a catalog of the available collections

The `/odata/$metadata` URL returns detailed data on the Entities and their Properties

It is easy to pull back the first 5 `Customers` like so:

We can sort by `CustomerName` (descending) like this:

We can choose to select only the data of interest so we aren't clogging up our network with data that don't want:

We can get a specific `Customer` by the `CustomerId` like this:

Or we can search for `Customers` that meet a specific criteria, in this case, `CompanyName` includes the string `fa`:

Things get REALLY interesting when we use expand to pull back child data also. Here we see the `Customer` object now has an `Orders` property that is an array of `Order` objects:

We can go deep on the expand expression (`$expand=Orders,Orders/Order_Details,Orders/Order_Details/Product`):

Create Search Route and Search View

Phew, that's a lot of background. Now lets put that odata url understanding to use and build a page that lets a user search for customers that match the information they enter into a search criteria page.

Using Flexbox Layout

What follows is exquisite.

`search-customer.less`

#search-customer {
    display: flex;
    flex-direction: row;
    flex: 1;
}

search-customer-criteria {
    background-color: orange;
    margin:20px;
}

search-customer-results {
    background-color: lawngreen;
    flex: 1;
    margin: 20px 20px 20px 0;
}

`search-customer.html`

<template>
    <div id="search-customer">
        <search-customer-criteria></search-customer-criteria>
        <search-customer-results></search-customer-results>
    </div>
</template>

`search-customer-criteria.html`

<template>
    <h3>Customer Search</h3>
</template>

`search-customer-results.html`

<template>
    <h3>Results</h3>
</template>

Create Search Criteria View

Create Search Results View

Notes

`.less` files

When you add a .less file, right click it, choose web compiler - compile.

Aurelia `.d.ts` File Generation

The Aurelia libraries contain ES6 / ES7 code that is transpiled by the babel transpiler.
The ES6 / ES7 code in these libraries contains type annotations
- ContainerConfiguration interface type annotation in aurelia-dependency-injection library
- More Type Annotations in aurelia-dependency-injection library
When the Aurelia library code is built (transpiled), a babel plugin called babel-dts-generator extracts the type annotations and the associated code comments and generates a .d.ts TypeScript type definition file.

Aurelia `api.json` File Generation

Aurelia Reference Documentation is provided by an Aurelia application that is driven by api.json files, also generated as part of the build and release process.

The Aurelia libraries' .d.ts files are run through TypeDoc to generate a (large) api.json file which contains all of the type annotations in the Aurelia library being built as well as all the types from the dependent libraries.
From this (large) api.json file, the type information (for just this library) is extracted to the release api.json file using the Gulp TypeDoc Extractor