From 72ab016e7500216eecbcd804b3eb9f75eb08ab64 Mon Sep 17 00:00:00 2001 From: Lex Zhukov Date: Fri, 28 Apr 2017 15:31:26 +0300 Subject: [PATCH] docs: update docs for 1.0.0 (#1034) --- CHANGELOG.md | 19 ++-- .../articles/001-getting-started/index.md | 12 +-- .../002-installation-guidelines/index.md | 18 ++-- .../011-changing-color-scheme/index.md | 2 +- .../articles/012-project-structure/index.md | 86 +++++++++---------- .../articles/013-create-new-page/index.md | 24 +++--- .../014-switch-to-blur-theme/index.md | 2 +- docs/contents/articles/015-sidebar/index.md | 2 +- docs/contents/articles/016-spinner/index.md | 4 +- docs/templates/index.jade | 6 +- docs/templates/layout.jade | 4 +- package.json | 6 +- yarn.lock | 22 +++-- 13 files changed, 107 insertions(+), 100 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 487cec33..61c6b5c2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -75,8 +75,10 @@ ### How to use AOT -* run `npm run build:aot` -* run `npm run server:prod` +```bash + npm run build:aot + npm run server:prod +``` ### How to update @@ -98,9 +100,6 @@ * Angular 2.2.3 * Dependencies updated -### Bug Fixes - - ### How to update * Pull sources from git, merge accordingly @@ -120,9 +119,6 @@ Tree package does not support angular 2.0 currently so it was hidden from the me * Angular 2.0 * Dependencies updated -### Bug Fixes - - ### How to update * Pull sources from git, merge accordingly @@ -143,9 +139,6 @@ Tree package does not support RC6 currently so it was hidden from the menu. * Angular rc.6 * Dependencies updated -### Bug Fixes - - ### How to update * Pull sources from git, merge accordingly @@ -167,8 +160,6 @@ Not all packages used in ng2-admin support RC5 at the moment, so we suggest wait * Webpack 2 * Dependencies updated -### Bug Fixes - ### Breaking changes Things to consider: @@ -181,7 +172,7 @@ Things to consider: ### How to update -* Read Angluar RC4 -> RC5 [migration guide](https://angular.io/docs/ts/latest/cookbook/rc4-to-rc5.html) +* Read Angular RC4 -> RC5 [migration guide](https://angular.io/docs/ts/latest/cookbook/rc4-to-rc5.html) * Pull sources from git, merge accordingly * remove `node_modules` * run `npm install` diff --git a/docs/contents/articles/001-getting-started/index.md b/docs/contents/articles/001-getting-started/index.md index 5b6796ed..3df5d065 100644 --- a/docs/contents/articles/001-getting-started/index.md +++ b/docs/contents/articles/001-getting-started/index.md @@ -8,7 +8,7 @@ template: article.jade ## What is ng2-admin? -ng2-admin is a front-end Admin Dashboard template based on Angular 2, Bootstrap 4 and Webpack. That means all the +ng2-admin is a front-end Admin Dashboard template based on Angular, Bootstrap 4 and Angular CLI. That means all the data you can see on graphs, charts and tables is mocked in Javascript so you can use the backend of your choice with no limitations. @@ -21,14 +21,14 @@ ecosystem for building production-ready application or prototypes. Frameworks like Bootstrap provide a number of components, but usually it's not enough to build a real-world app. This template comes with lots of popular UI components with a unified color scheme, -plus it is based on a modern Angular 2 framework and has a flexible component based structure. +plus it is based on a modern Angular framework and has a flexible component based structure. -You can also use ng2-admin for the purpose of learning Angular 2. +You can also use ng2-admin for the purpose of learning Angular. ## List of features -* Angular 2 -* Webpack 2 +* Angular 2+ +* Angular CLI * Bootstrap 4 CSS Framework * SASS * [Smart Table](http://akveo.com/ng2-admin/#/pages/tables/smarttables) @@ -47,4 +47,4 @@ Welcome aboard! You can start with the [Installation Guidelines](/ng2-admin/articles/002-installation-guidelines/). There we describe how you can download and run the template on your local machine. -Good luck and have fun! \ No newline at end of file +Good luck and have fun! diff --git a/docs/contents/articles/002-installation-guidelines/index.md b/docs/contents/articles/002-installation-guidelines/index.md index 2b2c54b8..6e9a7dec 100644 --- a/docs/contents/articles/002-installation-guidelines/index.md +++ b/docs/contents/articles/002-installation-guidelines/index.md @@ -17,7 +17,7 @@ If you don't have any of these tools installed already, you will need to: * Download and install [git](https://git-scm.com/) * Download and install nodejs [https://nodejs.org](https://nodejs.org) -**Note**: Make sure you have Node version >= 4.0 and NPM >= 3 +**Note**: Make sure you have Node version >= 6.0 and NPM >= 3 ## Clone repository and install dependencies You will need to clone the source code of ng2-admin GitHub repository: @@ -31,6 +31,12 @@ After the repository is cloned, go inside of the repository directory and instal cd ng2-admin npm install ``` +or +```bash +cd ng2-admin +yarn +``` + This will setup a working copy of ng2-admin on your local machine. ## Running local copy @@ -41,18 +47,20 @@ To run a local copy in development mode, execute: npm start ``` -Go to http://0.0.0.0:3000 or http://localhost:3000 in your browser. +Go to http://0.0.0.0:4200 or http://localhost:4200 in your browser. To run the local copy in production mode and build the sources, execute: ```bash -npm run prebuild:prod && npm run build:prod && npm run server:prod +npm run start:prod +``` +or in AOT mode +```bash +npm run start:prod:aot ``` This will clear up your dist folder (where release files are located), generate a release build and start the built-in server. Now you can copy the sources from the `dist` folder and use it with any backend framework or simply put it under a web server. - -For addition information about creating a build, please check out [Angular2 Webpack Starter documentation](https://github.com/AngularClass/angular2-webpack-starter) diff --git a/docs/contents/articles/011-changing-color-scheme/index.md b/docs/contents/articles/011-changing-color-scheme/index.md index 1931bd87..7da79861 100644 --- a/docs/contents/articles/011-changing-color-scheme/index.md +++ b/docs/contents/articles/011-changing-color-scheme/index.md @@ -8,7 +8,7 @@ template: article.jade We tried to make the process of color scheme customization as easy as possible. -By default ng2-admin has three built-in color profiles: ng2 (default blue sheme), mint and blur. +By default ng2-admin has three built-in color profiles: ng2 (default blue scheme), mint and blur. This article will help you to create your own color profile. Let's say you want to make ng2-admin dark theme. diff --git a/docs/contents/articles/012-project-structure/index.md b/docs/contents/articles/012-project-structure/index.md index 7ccd85ad..0b71e71e 100644 --- a/docs/contents/articles/012-project-structure/index.md +++ b/docs/contents/articles/012-project-structure/index.md @@ -6,70 +6,66 @@ group: Customization template: article.jade --- -The project structure is originally based on [Angular2 Webpack Starter](https://github.com/AngularClass/angular2-webpack-starter#file-structure). We made some changes we thought would be better in our particular case. - The directory structure of this template is as follows: ``` ng2-admin/ - ├──config/ * webpack build configuration - │ ├──head-config.common.js * configuration for head elements in index.html + ├──e2e/ + │ ├──tsconfig.e2e.json * typescript config that protractor use for e2e tests + │ + ├──src/ * source files that will be compiled to javascript + │ ├──typings.d.ts * custom typings for third-party modules │ │ - │ ├──helpers.js * helper functions for our configuration files + │ ├──index.html * application layout │ │ - │ ├──webpack.dev.js * development webpack config + │ ├──main.ts * entry file for our browser environment │ │ - │ ├──webpack.prod.js * production webpack config + │ ├──polyfills.ts * polyfills file │ │ - │ ├──webpack.test.js * testing webpack config - │ │ - │ ├──electron/ * electron webpack config - │ │ - │ └──html-elements-plugin/ * html elements plugin - │ - ├──src/ * source files that will be compiled to javascript - │ ├──custom-typings.d.ts * custom typings for third-party modules - │ │ - │ ├──desktop.ts * electron window initialization - │ │ - │ ├──index.html * application layout - │ │ - │ ├──main.browser.ts * entry file for our browser environment - │ │ - │ ├──package.json * electrons package.json - │ │ - │ ├──polyfills.browser.ts * polyfills file - │ │ - │ ├──vendor.browser.ts * vendors file - │ │ - │ ├──app/ * application code - our working directory + │ ├──app/ * application code - our working directory + │ │ ├──pages/ + │ │ │ ├──pages.menu.ts * menu pages routes │ │ │ - │ │ ├──app.component.ts * main application component + │ │ ├──app.component.ts * main application component │ │ │ + │ │ ├──app.module.ts * main application module │ │ │ - │ │ ├──app.menu.ts * menu pages routes - │ │ │ - │ │ ├──app.module.ts * main application module - │ │ │ - │ │ ├──app.routes.ts * application routes + │ │ ├──app.routing.ts * application routes + │ │ │ + │ │ ├──app.translation.module.ts * main translation module │ │ │ - │ │ ├──global.state.ts * global application state for data exchange between components + │ │ ├──global.state.ts * global application state for data exchange between components │ │ │ - │ │ ├──environment.ts * environment provider + │ │ ├──environment.ts * environment provider │ │ │ - │ │ ├──app.scss * application styles + │ │ ├──app.component.scss * application styles │ │ │ - │ │ ├──pages/ * application pages components, place where you can create pages and fill them with components + │ │ ├──pages/ * application pages components, place where you can create pages and fill them with components │ │ │ - │ │ └──theme/ * template global components/directives/pipes and styles + │ │ └──theme/ * template global components/directives/pipes and styles │ │ - │ └──assets/ * static assets are served here + │ └──assets/ * static assets are served here │ │ - ├──tslint.json * typescript lint config - ├──typedoc.json * typescript documentation generator - ├──tsconfig.json * config that webpack uses for typescript - └──package.json * what npm uses to manage it's dependencies + ├──.angular-cli.json * Angular CLI config + │ + ├──Dockerfile * Docker config + │ + ├──karma.conf.js * config that karma use for unit tests + │ + ├──protractor.conf.js * config that protractor use for e2e tests + │ + ├──.angular-cli.json * Angular CLI config + │ + ├──.stylelintrc.json * SASS/CSS lint config + │ + ├──tslint.json * typescript lint config + │ + ├──typedoc.json * typescript documentation generator + │ + ├──tsconfig.json * config that webpack uses for typescript + │ + └──package.json * what npm uses to manage it's dependencies ``` In our template we tried to separate the theme layer and presentation layer. We believe most of other templates have them combined. That's why when you start developing using them, it gets very hard for you to remove things you diff --git a/docs/contents/articles/013-create-new-page/index.md b/docs/contents/articles/013-create-new-page/index.md index 0644d545..72ac1730 100644 --- a/docs/contents/articles/013-create-new-page/index.md +++ b/docs/contents/articles/013-create-new-page/index.md @@ -6,39 +6,40 @@ group: Customization template: article.jade --- -ng2-admin uses [Angular 2 Component Router](https://angular.io/docs/ts/latest/guide/router.html) for navigation. +ng2-admin uses [Angular Component Router](https://angular.io/docs/ts/latest/guide/router.html) for navigation. We strongly recommend to follow this page structure in your application. If it does not fit your needs please create a GitHub issue and tell us why. We would be glad to discuss. -Basically any page is just a common Angular 2 Component with a route defined for it. +Basically any page is just a common Angular Component with a route defined for it. ## Let's create a blank page in 6 easy steps 1) Create a new directory for our new page inside of `src/app/pages`. We can call the directory `new`.

-2) Then let's create a blank angular 2 component for our page called 'new.component.ts' inside of `src/app/pages/new`: +2) Then let's create a blank angular component for our page called 'new.component.ts' inside of `src/app/pages/new`: ```javascript -import {Component} from '@angular/core'; +import { Component } from '@angular/core'; @Component({ selector: 'new', - template: `My page content here` + template: `My page content here`, }) export class NewComponent { constructor() {} } ``` -This will create a simple Angular 2 component. For more detail please check out [official Angular 2 documentation](https://angular.io/docs/ts/latest/guide/displaying-data.html). +This will create a simple Angular component. For more detail please check out [official Angular documentation](https://angular.io/docs/ts/latest/guide/displaying-data.html).

3) After that we should create our component routing called `new.routing.ts` in the `new` directory. ```javascript -import { Routes, RouterModule } from '@angular/router'; +import { Routes, RouterModule } from '@angular/router'; + import { NewComponent } from './new.component'; const routes: Routes = [ @@ -57,12 +58,15 @@ export const routing = RouterModule.forChild(routes); ```javascript import { NgModule } from '@angular/core'; import { CommonModule } from '@angular/common'; +import { FormsModule } from '@angular/forms'; + import { NewComponent } from './new.component'; import { routing } from './new.routing'; @NgModule({ imports: [ CommonModule, + FormsModule, routing ], declarations: [ @@ -124,14 +128,14 @@ const routes: Routes = [ component: Pages, children: [ { path: '', redirectTo: 'dashboard', pathMatch: 'full' }, - { path: 'dashboard', loadChildren: 'app/pages/dashboard/dashboard.module#DashboardModule' }, - { path: 'new', loadChildren: 'app/pages/new/new.module#NewModule' } + { path: 'dashboard', loadChildren: './dashboard/dashboard.module#DashboardModule' }, + { path: 'new', loadChildren: './new/new.module#NewModule' } ] } ]; ```
-And that's it! Now your page is available by the following this url [http://localhost:3000/#/pages/new](http://localhost:3000/#/pages/new). +And that's it! Now your page is available by the following this url [http://localhost:4200/#/pages/new](http://localhost:4200/#/pages/new). Plus, your page is registered inside the sidebar menu. If you don't want to have a link in the menu - just remove the `menu` declaration from the `pages.menu.ts` file. diff --git a/docs/contents/articles/014-switch-to-blur-theme/index.md b/docs/contents/articles/014-switch-to-blur-theme/index.md index 119c8ef9..4fa14c9a 100644 --- a/docs/contents/articles/014-switch-to-blur-theme/index.md +++ b/docs/contents/articles/014-switch-to-blur-theme/index.md @@ -74,7 +74,7 @@ to @import 'colorSchemes/blur'; ``` -Additionaly, if you would like to use some different background, replace the following images: +Additionally, if you would like to use some different background, replace the following images: - `src/assets/img/blur-bg.jpg` (main background image) - `src/assets/img/blur-bg-blurred.jpg` (blurred background image used on panels) diff --git a/docs/contents/articles/015-sidebar/index.md b/docs/contents/articles/015-sidebar/index.md index fcfaffd0..eabc03b4 100644 --- a/docs/contents/articles/015-sidebar/index.md +++ b/docs/contents/articles/015-sidebar/index.md @@ -28,7 +28,7 @@ All menu items are located inside the `src/app/app.routes.ts` file. Each route i path: 'dashboard', component: Dashboard, data: { - // here additionaly we define how the menu item should look + // here additionally we define how the menu item should look menu: { title: 'Dashboard', // menu title icon: 'ion-android-home', // menu icon diff --git a/docs/contents/articles/016-spinner/index.md b/docs/contents/articles/016-spinner/index.md index 91b5327c..3d6589a5 100644 --- a/docs/contents/articles/016-spinner/index.md +++ b/docs/contents/articles/016-spinner/index.md @@ -8,7 +8,7 @@ template: article.jade Theme Spinner `BaThemeSpinner` is a small service helper allowing you to show a preloader spinner while executing some long-running tasks. -This is the same spinner you can see after reloading a page - it is shown while the application is initializing Angular 2 and loading charts and images. +This is the same spinner you can see after reloading a page - it is shown while the application is initializing Angular and loading charts and images. The user interface in quite simple: there are two public methods: `show` and `hide`. @@ -58,4 +58,4 @@ Last thing you need to do is to register your loader: BaThemePreloader.registerLoader(this._loadData()); ``` -That's basically it! Once your data is loaded and all other registered loaders are completed - the spinner will be hidden. \ No newline at end of file +That's basically it! Once your data is loaded and all other registered loaders are completed - the spinner will be hidden. diff --git a/docs/templates/index.jade b/docs/templates/index.jade index 33a56094..de106812 100644 --- a/docs/templates/index.jade +++ b/docs/templates/index.jade @@ -2,7 +2,7 @@ extends layout block title - | Admin HTML template based on Angular 2, Bootstrap 4 and Webpack + | Admin HTML template based on Angular, Bootstrap 4 and Angular CLI block content div.hero @@ -10,7 +10,7 @@ block content div.wrap div.text strong ng2-#[span.white-text admin] - div.minitext Angular 2 admin panel front-end framework + div.minitext Angular admin panel front-end framework div.buttons-unit a.button(href=installationArticleUrl) Installation guidelines a.button(href=firstArticleUrl) Documentation @@ -27,7 +27,7 @@ block content div.why-item img(src=contents.images['why-structure.svg'].url) h4 Awesome structure - p Component-based structure is the best choice for large Angular 2 applications. + p Component-based structure is the best choice for large Angular applications. div.why-item img(src=contents.images['why-design.svg'].url) h4 Neat design diff --git a/docs/templates/layout.jade b/docs/templates/layout.jade index 23cf5ba4..48960b72 100644 --- a/docs/templates/layout.jade +++ b/docs/templates/layout.jade @@ -37,8 +37,8 @@ html(lang='en') block content h2 Welcome to blur admin! footer.wrap - div.left Powered by Angular 2, Bootstrap 4, Webpack and many more... + div.left Powered by Angular, Bootstrap 4, Angular CLI and many more... div.right - | © 2015–2016 Akveo LLC
+ | © 2017 Akveo LLC
| Documentation licensed under #[a(href='https://creativecommons.org/licenses/by/4.0/') CC BY 4.0]. a(href='https://github.com/akveo/ng2-admin', class='github-fork-ribbon', title="Star & Fork on GitHub") diff --git a/package.json b/package.json index 473f0a5e..407536ad 100644 --- a/package.json +++ b/package.json @@ -19,6 +19,8 @@ "start": "ng serve", "start:hmr": "ng serve --hmr", "start:aot": "ng serve --aot", + "start:prod": "ng serve --prod", + "start:prod:aot": "ng serve --prod --aot", "build": "npm run clean:dist && ng build", "build:prod": "npm run build -- --prod", "build:prod:aot": "npm run build -- --aot", @@ -32,7 +34,8 @@ "e2e": "ng e2e", "clean:dist": "npm run rimraf -- dist", "clean:coverage": "npm run rimraf -- coverage", - "gh-pages": "wintersmith build -C docs && gh-pages -d docs/build" + "gh-pages": "wintersmith build -C docs && gh-pages -d docs/build", + "docs:serve": "wintersmith preview -C docs" }, "private": true, "dependencies": { @@ -110,6 +113,7 @@ "tslint-eslint-rules": "3.5.1", "typescript": "2.2.2", "typogr": "0.6.6", + "underscore": "1.8.3", "wintersmith": "2.2.5", "wintersmith-sassy": "1.1.0" } diff --git a/yarn.lock b/yarn.lock index aa165398..83f06185 100644 --- a/yarn.lock +++ b/yarn.lock @@ -5637,15 +5637,16 @@ read@1, read@~1.0.1, read@~1.0.7: dependencies: mute-stream "~0.0.4" -"readable-stream@1 || 2", readable-stream@^2.0.1, readable-stream@^2.0.2, readable-stream@^2.0.5, readable-stream@~2.0.0, readable-stream@~2.0.5: - version "2.0.6" - resolved "https://registry.yarnpkg.com/readable-stream/-/readable-stream-2.0.6.tgz#8f90341e68a53ccc928788dacfcd11b36eb9b78e" +"readable-stream@1 || 2", "readable-stream@^2.0.0 || ^1.1.13", readable-stream@^2.1.4, readable-stream@^2.1.5, readable-stream@^2.2.6: + version "2.2.9" + resolved "https://registry.yarnpkg.com/readable-stream/-/readable-stream-2.2.9.tgz#cf78ec6f4a6d1eb43d26488cac97f042e74b7fc8" dependencies: + buffer-shims "~1.0.0" core-util-is "~1.0.0" inherits "~2.0.1" isarray "~1.0.0" process-nextick-args "~1.0.6" - string_decoder "~0.10.x" + string_decoder "~1.0.0" util-deprecate "~1.0.1" readable-stream@1.0, "readable-stream@>=1.0.33-1 <1.1.0-0", readable-stream@~1.0.2: @@ -5666,16 +5667,15 @@ readable-stream@^1.0.33, readable-stream@~1.1.9: isarray "0.0.1" string_decoder "~0.10.x" -"readable-stream@^2.0.0 || ^1.1.13", readable-stream@^2.1.4, readable-stream@^2.1.5, readable-stream@^2.2.6: - version "2.2.9" - resolved "https://registry.yarnpkg.com/readable-stream/-/readable-stream-2.2.9.tgz#cf78ec6f4a6d1eb43d26488cac97f042e74b7fc8" +readable-stream@^2.0.1, readable-stream@^2.0.2, readable-stream@^2.0.5, readable-stream@~2.0.0, readable-stream@~2.0.5: + version "2.0.6" + resolved "https://registry.yarnpkg.com/readable-stream/-/readable-stream-2.0.6.tgz#8f90341e68a53ccc928788dacfcd11b36eb9b78e" dependencies: - buffer-shims "~1.0.0" core-util-is "~1.0.0" inherits "~2.0.1" isarray "~1.0.0" process-nextick-args "~1.0.6" - string_decoder "~1.0.0" + string_decoder "~0.10.x" util-deprecate "~1.0.1" readdir-scoped-modules@^1.0.0: @@ -6952,6 +6952,10 @@ umask@~1.1.0: version "1.1.0" resolved "https://registry.yarnpkg.com/umask/-/umask-1.1.0.tgz#f29cebf01df517912bb58ff9c4e50fde8e33320d" +underscore@1.8.3: + version "1.8.3" + resolved "https://registry.yarnpkg.com/underscore/-/underscore-1.8.3.tgz#4f3fb53b106e6097fcf9cb4109f2a5e9bdfa5022" + uniq@^1.0.1: version "1.0.1" resolved "https://registry.yarnpkg.com/uniq/-/uniq-1.0.1.tgz#b31c5ae8254844a3a8281541ce2b04b865a734ff"