aurelia / documentation

The documentation for Aurelia.
MIT License
105 stars 110 forks source link

Issues in Adding Navigation section of Get Started document #148

Closed adriatic closed 9 years ago

adriatic commented 9 years ago

This is the Adding Navigation Section and here are the issues:

INFO [aurelia] Aurelia Started
system.src.js:3987 GET http://localhost:9000/dist/css.js 404 (Not Found)M @ system.src.js:3987(anonymous function) @ system.src.js:3987b @ shim.min.js:1526o.fetch @ system.src.js:3987(anonymous function) @ system.src.js:3987(anonymous function) @ system.src.js:3987(anonymous function) @ system.src.js:3987(anonymous function) @ system.src.js:3987(anonymous function) @ system.src.js:3987(anonymous function) @ system.src.js:3987(anonymous function) @ system.src.js:3987(anonymous function) @ system.src.js:3987f @ shim.min.js:1415(anonymous function) @ shim.min.js:1423b.exports @ shim.min.js:453b.(anonymous function) @ shim.min.js:1625f @ shim.min.js:1596q @ shim.min.js:1600
shim.min.js:1444 Unhandled promise rejection Error: XHR error (404 Not Found) loading http://localhost:9000/dist/css.js(…)

Note that this is precisely the problem I was facing for last several weeks using my own mini-app, patterned after Skeleton Navigation vers 0.17.0 and 0.18.0

GET http://localhost:9000/dist/css.js 404 (Not Found)M @ system.src.js:3987(anonymous function) @ system.src.js:3987b @ shim.min.js:1526o.fetch @ system.src.js:3987(anonymous function) @ system.src.js:3987(anonymous function) @ system.src.js:3987(anonymous function) @ system.src.js:3987(anonymous function) @ system.src.js:3987(anonymous function) @ system.src.js:3987(anonymous function) @ system.src.js:3987(anonymous function) @ system.src.js:3987(anonymous function) @ system.src.js:3987f @ shim.min.js:1415(anonymous function) @ shim.min.js:1423b.exports @ shim.min.js:453b.(anonymous function) @ shim.min.js:1625f @ shim.min.js:1596q @ shim.min.js:1600
adriatic commented 9 years ago

Comparisons between A (https://github.com/aurelia/skeleton-navigation/releases/tag/0.18.0) and B (https://github.com/aurelia/documentation/blob/master/English/get-started.md)

(I believe that these two should be at least in sync if not identical, since

npm install -g yo generator-aurelia
yo aurelia

make these two applications identical at the beginning.

Case 1

app.js in A

export class App {
  configureRouter(config, router){
    config.title = 'Aurelia';
    config.map([
      { route: ['','welcome'],  name: 'welcome',      moduleId: 'welcome',      nav: true, title:'Welcome' },
      { route: 'users',         name: 'users',        moduleId: 'users',        nav: true, title:'Github Users' },
      { route: 'child-router',  name: 'child-router', moduleId: 'child-router', nav: true, title:'Child Router' }
    ]);

    this.router = router;
  }
}

app.js in B

import 'bootstrap';
import 'bootstrap/css/bootstrap.css!';

export class App {
  configureRouter(config, router){
    config.title = 'Aurelia';
    config.map([
      { route: ['','welcome'], name: 'welcome', moduleId: 'welcome', nav: true, title:'Welcome' }
    ]);

    this.router = router;
  }
}

Disregarding the size of the `config.map``` object the confusing part is the presence of

import 'bootstrap';
import 'bootstrap/css/bootstrap.css!';

in B and absence in A. Since application A works just fine that makes the two import statements in B causing the trouble described above.

Case 2

The app.js as appearing in A dist folder is completely confusing when compared with any of the two versions shown above


Note: the instructions on how to access the third party libraries (in particular, those that like bootstrap require access to css files and javascript files) were confusing to me since the day one (and they kept changing a lot)

Most people would consider my remarks here "trivial" and that is a mistake of the same magnitude like calling Euclid's 5 axioms of geometry trivial. Please help making this issue as clear as possible - even to the village idiots.

adriatic commented 9 years ago

This issue is a showstopper for my complete analysis and verification of the information provided in https://github.com/aurelia/documentation/blob/master/English/get-started.md

EisenbergEffect commented 9 years ago

Apologies. The getting started guide is actually a few days behind our latest release. Normally, that doesn't happen, but it slipped through. The new release has new features that affect CSS loading in particular. The new guide will be updated today or tomorrow.

That said, the guide, while it may be different, if the src files are deleted and the instructions are followed, should result in a working app, sans the need for the css plugin, which the error log should inform the user of (that's coming from system.js/jspm). Nothing that would make the old guide produce a working app has been removed, simply better ways of handling the scenarios have been added.

No changes in the mechanism for loading 3rd party JS have occurred in the history of our project. Our recommendation for how best to load CSS has only changed a few days ago with the addition of the new features. Prior to that, there were multiple ways you could do it and Aurelia simply had no opinion on that matter. We are changing that with this latest release now that we have been able to remove html imports, expand our view pipeline and enhance our bundling system.

adriatic commented 9 years ago

Perfect explanation thank you Rob.

I was really waiting for removal of html imports, expansion of view pipeline and enhancements the bundling system to continue my epic - where the very first action would be to replace my own "minimal" Aurelia app with your (really well written) equivalent and than build on top of it.

Knowing that the Getting started guide will be refreshed, I will wait for it :-)

EisenbergEffect commented 9 years ago

Yes indeed. Again, sorry for the delay there.

adriatic commented 9 years ago

I forgot to make another important point - using bootstrap just as a "model" for it

I think that all these should be presented in the same "view" in the documentation (as different from current get started, where jspm install bootstrap --save appears on page x and then much later on page y, you get to see a request, or import, without the necessary comments on possible "overrides" done in ''jspm install`` for example.

This issue is consistently kept "murky" for no good reason.

If you think that this is "below" the Aurelia Documentation level, I know that it is not below Aurelia-Guides level; so if you show me the basics of the logics of pairing between the form of fetching a package from a remote site and the form of using it internally, I will write the article on this in Aurelia Guides

EisenbergEffect commented 9 years ago

I think this has all been addressed now.