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

1. Install SQL Server (Express)

2. Download Northwind Database Backup

3. 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

1. Rename the folder: aurelia-axel ➡️ aurelia-axel-northwind
2. Rename the solution file ➡️ aurelia-axel-northwind.sln
3. Switch to the aurelia-axel-northwind folder
4. Rename the project file ➡️ aurelia-axel-northwind.csproj
5. Switch back to the main folder
6. Open the solution in Visual Studio (run as administrator)
7. Right click the old project (which didn't load) and remove it from the solution.
8. Right click the solution and add - existing project and browse to the renamed project file
9. The project should load

Create EF Model

1. Create new empty project

   

   

2. Delete the (unhelpful) Class1.cs

3. Add Entity Framework Model

   

   

   

   

   

   

   

   

4. Bask in the glory of your automatically created EF model !! 😄

   

   

Create OData Controller

1. Make sure you did a rebuild on the solution

2. Add a reference to the EF project

   

   

3. Add the connection string from the EF project's app.config to the web project's web.config

   

   

4. Add the OData controller

   

   

   

   

5. Copy the using statements to the WebApiConfig.cs file

   

   

6. Copy the OData code block to the WebApiConfig.cs file

   

   

   

7. Increase the Customer OData Controller's expand depth to 4 (from the default 2)

   

8. 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

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

Aurelia .d.ts File Generation

1. The Aurelia libraries contain ES6 / ES7 code that is transpiled by the babel transpiler.

2. 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

3. 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.

1. 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.
2. 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