Improve debug output for templating and information on importing css files

I am writing this with lots of details expecting that you might use parts of my text to improve the existing documentation :-)

The process of defining references to "third party" css files has too many degrees of freedom, making it feel as a trap - in my own experience this is the most confusing areas of Aurelia and it needs help both in cheat-sheet document and the templating debug output.

To show the problem, I will contrast the well known method of providing access to bootstrap in skeleton navigation application with my own problem of providing the access to KendoUI - where both bootstrap and KendoUI "live" in Github.

Accessing bootstrap from Github

Step 1: Declare application dependency on bootstrap by this line

"bootstrap": "github:twbs/bootstrap@^3.3.5",

in jspm section of the application's package.json file. This dependency creates the mapping between the application's internal name (bootstrap) and external name (github:twbs/bootstrap@^3.3.5) for the GitHub repository accessed by URL https://github.com/twbs/bootstrap.git (Note the absence of the version number in the URL itself - I will come back to KendoUI case later)

Since the package.json file is processed by jspm, the above defined information is persisted in the jspm generated config.js file here using the same format as package.json shown above.

Step 2: Add bootstrap to skeleton navigation app Once the initial installation step npm install successfully executed, the whole bootstrap module is added to the skeleton navigation app by executing the command that installs the client side dependencies:

jspm install

Note: this form of invoking the installation of the client side dependencies (without the -y argument) results with additional benefit of getting immediate warnings on any "version overwrites" that often get unnoticed and result with difficult debugging later).

Accessing bootstrap from inside (the skeleton navigation app)

_Editorial_ This is where the first chance for confusion exists as there are too many variants of ES6 import statement, which combined with the mapping of the internal and external names discussed in previous section can result with unnecessary complexity.

In addition to above (Aurelia independent) issues, Aurelia added the <require> HTML element as an additional method of providing access to a third party css file. Since this "private" <require> element is processed by the templating compiler, this issue is being added to templating issues.

The use of the <require> element is shown in app.html - line 3

<template>
  <require from="nav-bar.html"></require>
  <require from="bootstrap/css/bootstrap.css"></require>

  <nav-bar router.bind="router"></nav-bar>

  <div class="page-host">
    <router-view></router-view>
  </div>
</template>

The difficulty with the format <require from="bootstrap/css/bootstrap.css"></require> is in the need for the developer to maintain the relationship between the first component of the string "bootstrap/css/bootstrap.css" with the mapping defined in the package.json file discussed earlier.

In addition I would recommend adding the explanation (in the form of comments) stating why is ES6 format of import statement used in the main.js

import 'bootstrap';

This explanation should include the reason why is this import statement present in this file (as it is not obvious in my opinion) and how does the string 'boostrap' relate to the bootstrap module already installed in the skeleton application.

With all this huge introduction (provided for clarity and possible reuse in a different context), here is the problem with accessing KendoUI via https://github.com/telerik/kendo-ui-core

Using the identical approach described for boostrap acces, where the app.html file is

<template>

    <require from="bootstrap/css/bootstrap.css"></require>
    <require from="kendo-ui/src/styles/web/kendo.bootstrap.css!"></require>
    <require from="./nav-bar"></require>

    <nav-bar router.bind="router"></nav-bar>

    <div class="page-host">
        <router-view></router-view>
    </div>
</template>

running my app results with

GET http://localhost:9000/dist/css.js 404 (Not Found)
Unhandled promise rejection Error: XHR error (404 Not Found) loading http://localhost:9000/dist/css.js
    Error loading http://localhost:9000/dist/css.js
    Error loading http://localhost:9000/jspm_packages/github/telerik/kendo-ui-core@2015.3.1111/src/styles/web/kendo.bootstrap.css!http://localhost:9000/dist/css.js
    at o (http://localhost:9000/jspm_packages/system.js:4:12694)
    at XMLHttpRequest.s.onreadystatechange (http://localhost:9000/jspm_packages/system.js:4:13219)

Clearly the external / internal name mapping is bad as shown by

http://localhost:9000/jspm_packages/github/telerik/kendo-ui-core@2015.3.1111/src/styles/web/kendo.bootstrap.css!http://localhost:9000/dist/css.js

The only difference that I could see is the existence of the highlighted line shown below:

which says

module.exports = require("github:twbs/bootstrap@3.3.5/js/bootstrap");

and absence of a similar information in the case of KendoUI:

aurelia / templating

Improve debug output for templating and information on importing css files #221

Accessing bootstrap from Github

Accessing bootstrap from inside (the skeleton navigation app)