Home

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

  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.

image

image

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:

image

You will see something that looks like this:

image

Install Web Essentials

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

image

Install Web Compiler

Web Compiler

image

Generating Docs

TypeScript Docs

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

image

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

image

  1. Rename the folder: aurelia-axel :arrow_right: aurelia-axel-northwind
  2. Rename the solution file :arrow_right: aurelia-axel-northwind.sln
  3. Switch to the aurelia-axel-northwind folder
  4. Rename the project file :arrow_right: 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

image

Create EF Model

  1. Create new empty project

    image

    image

  2. Delete the (unhelpful) Class1.cs

  3. Add Entity Framework Model

    image

    image

    image

    image

    image

    image

    image

    image

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

    image

    image

Create OData Controller

  1. Make sure you did a rebuild on the solution

  2. Add a reference to the EF project

    image

    image

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

    image

    image

  4. Add the OData controller

    image

    image

    image

    image

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

    image

    image

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

    image

    image

    image

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

    image

  8. Rebuild and run in the browser

Play with OData URLs

The /odata URL returns a catalog of the available collections

image

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

image

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

image

We can sort by CustomerName (descending) like this:

image

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

image

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

image

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

image

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:

image

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

image

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.

image

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

  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