commit e6c8deb7e4956a115662d7b07de444939bbf2c9b Author: nixa <4dmitr@gmail.com> Date: Wed May 25 13:42:47 2016 +0300 Updates diff --git a/articles/001-getting-started/index.html b/articles/001-getting-started/index.html new file mode 100644 index 00000000..fc1fed04 --- /dev/null +++ b/articles/001-getting-started/index.html @@ -0,0 +1,86 @@ + + +
+ + + + +ng2-admin is a front-end Admin Dashboard template based on Angular 2, Bootstrap 4 and Webpack. That means all data you can see on graphs, charts tables is mocked in Javascript so you can use backend of your choice with no limitations.
+We believe that at the moment a lot of business applications have administration/management interfaces inside of them. Sometimes it’s not that obvious, but a lot of web applications have dashboards with panels, charts analytics, etc.
+ng2-admin aims to bootstrap the development of your product and provide 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 unified color scheme, plus it based on a modern Angular 2 framework and has a flexible components-based structure.
+As well you can use ng2-admin for learning purposes of Angular 2.
+Welcome abroad!
+You can start with Installation Guidelines. There we describe how you can download and run the template on you local machine.
+Good luck and have fun!
+ +Despite BlurAdmin can be run without any development experience, it would be much easier if you already have some development experience. In general following instructions allow you to run a local copy on your machine.
+If you don’t have any of these tools installed already, you will need to:
+Note: Make sure you have Node version >= 4.0 and NPM >= 3
+Once you have those, you should install these globals with npm install --global:
webpack
+npm install --global webpack
+
+webpack-dev-server
+npm install --global webpack-dev-server
+
+typings
+npm install --global typings
+
+typescript
+npm install --global typescript
+
+You will need to clone the source code of ng2-admin GitHub repository:
+git clone https://github.com/akveo/ng2-admin.git
+
+After repository is cloned, go inside of the repository directory and install dependencies:
+cd ng2-admin
+npm install
+
+This will setup a working copy of ng2-admin on your local machine.
+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.
+To run the local copy in production mode and build the sources, execute:
+npm run prebuild:prod && npm run build:prod && npm run server:prod
+
+This will clear up your dist folder (where release files are located), generate release build and start built-in server.
+Now you can copy the sources from a dist folder and use it with any backend framework or simple put in under some web server.
For addition information about build, please check out Angular2 Webpack Starter documentation
+ +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. +This article will help you to create your own color profile. +Let’s say you want to make ng2-admin dark theme.
+First we advice you to take some colorscheme file as a basis.
+For light themes we suggest taking src/app/theme/sass/conf/colorScheme/_mint.scss one and for dark src/app/theme/sass/conf/colorScheme/_blue.scss one.
+As we want a dark theme, we’re taking ng2.
1) Copy src/app/theme/sass/conf/colorScheme/_mint.scss to src/app/theme/sass/conf/colorScheme/_dark.scss.
2) Include your colorscheme file in src/app/theme/sass/conf/conf.scss.
To do this, replace
+@import 'colorSchemes/ng2';
+
+to
+@import 'colorSchemes/dark';
+
+3) Rename the color scheme enabled
+Open src/app/theme/theme.config.ts.
+Uncomment the following line
//this._baConfig.changeTheme({name: 'my-theme'});
+
+and put you theme name, in our case it is dark
this._baConfig.changeTheme({name: 'dark'});
+
+Beside this notifies the system which scheme currently enabled, it also puts a css class to a main element of the page. Thus you can freely create theme-specific css selectors in you code without braking other themes’ styles.
+For example like this:
+. dark .card-body {
+ background-color: white;
+}
+
+4) Change the colors
+Now your can start changing the colors.
+For example, after playing a bit with different colors, we changed 5 first main variables in _dark.scss file:
$body-bg: #636363;
+$bootstrap-panel-bg: rgba(#000000, 0.2);
+
+After this is done, you need to setup javascript to use same colors. These color are used for javascript charts and other components (maps, etc);
+Let’s completely change the JS colors to a new set.
+To do this, add the following code to the configuration block inside src/app/theme/theme.config.ts:
let colorScheme = {
+ primary: '#209e91',
+ info: '#2dacd1',
+ success: '#90b900',
+ warning: '#dfb81c',
+ danger: '#e85656',
+ };
+ this._baConfig.changeColors({
+ default: '#4e4e55',
+ defaultText: '#e2e2e2',
+ border: '#dddddd',
+ borderDark: '#aaaaaa',
+
+ primary: colorScheme.primary,
+ info: colorScheme.info,
+ success: colorScheme.success,
+ warning: colorScheme.warning,
+ danger: colorScheme.danger,
+
+ primaryLight: colorHelper.tint(colorScheme.primary, 30),
+ infoLight: colorHelper.tint(colorScheme.info, 30),
+ successLight: colorHelper.tint(colorScheme.success, 30),
+ warningLight: colorHelper.tint(colorScheme.warning, 30),
+ dangerLight: colorHelper.tint(colorScheme.danger, 30),
+
+ primaryDark: colorHelper.shade(colorScheme.primary, 15),
+ infoDark: colorHelper.shade(colorScheme.info, 15),
+ successDark: colorHelper.shade(colorScheme.success, 15),
+ warningDark: colorHelper.shade(colorScheme.warning, 15),
+ dangerDark: colorHelper.shade(colorScheme.danger, 15),
+
+ dashboard: {
+ blueStone: '#005562',
+ surfieGreen: '#0e8174',
+ silverTree: '#6eba8c',
+ gossip: '#b9f2a1',
+ white: '#10c4b5',
+ },
+ });
+
+Here we defined a list of main colors colorScheme and then made light and dark version of those using colorHelper methods.
+We also defined a couple of custom colors for dashboard charts.
That’s basically it! Right now your admin application should look like this:
+
For further reference, please look in
+src/app/theme/sass/conf/colorScheme/_ng2.scss, src/app/theme/sass/conf/colorScheme/_mint.scss and src/app/theme/sass/conf/colorScheme/_blur.scss)src/app/theme/theme.configProvider.js to understand which javascript colors can be changedProject structure was originally based on Angular2 Webpack Starter. 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/ * build configuration
+ │ ├──helpers.js * helper functions for our configuration files
+ │ ├──webpack.dev.js * development webpack config
+ │ ├──webpack.prod.js * production webpack config
+ │ └──webpack.test.js * testing webpack config
+ │
+ ├──src/ * source files that will be compiled to javascript
+ │ ├──main.browser.ts * entry file for our browser environment
+ │ │
+ │ ├──index.html * application layout
+ │ │
+ │ ├──polyfills.ts * polyfills file
+ │ │
+ │ ├──vendor.ts * vendors file
+ │ │
+ │ ├──custom-typings.d.ts * custom typings for third-party modules
+ │ │
+ │ ├──platform/ * platform dependent imports
+ │ │
+ │ ├──app/ * application code - our working directory
+ │ │ │
+ │ │ ├──app.component.ts * main application component
+ │ │ │
+ │ │ ├──app.loader.ts * requires initial css styles (most important for application loading stage)
+ │ │ │
+ │ │ ├──app.menu.ts * sidebar menu configuration
+ │ │ │
+ │ │ ├──app.state.ts * global application state for data exchange between components
+ │ │ │
+ │ │ ├──app.scss * application styles
+ │ │ │
+ │ │ ├──pages/ * application pages components, place where you can create pages and fill them with components
+ │ │ │
+ │ │ └──theme/ * template global components/directives/pipes and styles
+ │ │
+ │ └──assets/ * static assets are served here
+ │
+ │
+ ├──tslint.json * typescript lint config
+ ├──typedoc.json * typescript documentation generator
+ ├──tsconfig.json * config that webpack uses for typescript
+ ├──typings.json * our typings manager
+ ├──package.json * what npm uses to manage it's dependencies
+ ├──bower.json * DEPRECATED - moving to npm as primary package manager for all dependenties
+ └──.bowerrc * DEPRECARD - temporary bower configuration
+In our template we tried to separate 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 don’t need.
+ +Blur admin uses Angular UI router for navigation.
+That means to create new page you need to basically configure ui-router state.
We strongly recommend to follow pages structure in your application. +If it doesn’t fit your needs please create a GitHub issue and tell us why. We would be glad to discuss.
+Also we recommend to put pages to separate modules. +This will allow you to easily switch off some pages in the future if needed.
+0) Let’s assume we want to create a blank page with title ‘My New Page’
+1) Let’s Create a new directory to contain our new page inside of src/app/pages. Let’s call this directory myNewPage.
2) Then let’s create blank angular module to contain our page called ‘myNewPage.module.js’ inside of src/app/pages/myNewPage:
(function () {
+;
+
+ angular.module('BlurAdmin.pages.myNewPage', [])
+ .config(routeConfig);
+
+ /** @ngInject */
+ function routeConfig() {
+
+ }
+
+})();
+
+3) Then let’s create empty html file called my-new-page.html inside of src/app/pages/myNewPage.
4) Lastly let’s create ui router state for this page. To do this we need to modify module.js file we created on step 2:
+(function () {
+;
+
+ angular.module('BlurAdmin.pages.myNewPage', [])
+ .config(routeConfig);
+
+ /** @ngInject */
+ function routeConfig($stateProvider) {
+ $stateProvider
+ .state('myNewPage', {
+ url: '/myNewPage',
+ templateUrl: 'app/pages/myNewPage/my-new-page.html',
+ title: 'My New Page',
+ sidebarMeta: {
+ order: 800,
+ },
+ });
+ }
+
+})();
+
+That’s it! Your can now open your new page either from sidebar or through hash URL.
+ +If you want to switch theme to the blur, you need to follow 3 simple steps:
+1) Blur color scheme needs some javascript to calculate initial background offsets for panels.
+That’s why we need to tell the system that we want to use blur theme by specifying this in src/app/theme/theme.config.ts:
this._baConfig.changeTheme({name: 'blur'});
+
+2) Also you need to change some colors. +For our blur theme we use following configuration:
+ let colorScheme = {
+ primary: '#209e91',
+ info: '#2dacd1',
+ success: '#90b900',
+ warning: '#dfb81c',
+ danger: '#e85656',
+ };
+ this._baConfig.changeColors({
+ default: '#4e4e55',
+ defaultText: '#e2e2e2',
+ border: '#dddddd',
+ borderDark: '#aaaaaa',
+
+ primary: colorScheme.primary,
+ info: colorScheme.info,
+ success: colorScheme.success,
+ warning: colorScheme.warning,
+ danger: colorScheme.danger,
+
+ primaryLight: colorHelper.tint(colorScheme.primary, 30),
+ infoLight: colorHelper.tint(colorScheme.info, 30),
+ successLight: colorHelper.tint(colorScheme.success, 30),
+ warningLight: colorHelper.tint(colorScheme.warning, 30),
+ dangerLight: colorHelper.tint(colorScheme.danger, 30),
+
+ primaryDark: colorHelper.shade(colorScheme.primary, 15),
+ infoDark: colorHelper.shade(colorScheme.info, 15),
+ successDark: colorHelper.shade(colorScheme.success, 15),
+ warningDark: colorHelper.shade(colorScheme.warning, 15),
+ dangerDark: colorHelper.shade(colorScheme.danger, 15),
+
+ dashboard: {
+ blueStone: '#005562',
+ surfieGreen: '#0e8174',
+ silverTree: '#6eba8c',
+ gossip: '#b9f2a1',
+ white: '#10c4b5',
+ },
+ });
+
+3) CSS should also be recompiled.
+Before running build command, switch to blur color profile.
+To do so replace theme in src/app/theme/sass/conf/conf.scss:
@import 'colorScheme/ng2';
+
+to
+@import 'colorScheme/blur';
+
+Additionaly, 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)We suggest using 10px Gaussian blur to blur an original image.
+That’s it! You have successfully blurred your theme! Run npm start and check it out.
Sidebar is used to provide convenient way of navigation in the application. +Application support only one sidebar per angular application. +That means sidebar is basically a singletone object. +Currently sidebar supports level 1 and 2 sub menus.
+Sidebar can be added to the page using BaSidebar component:
<ba-sidebar></ba-sidebar>
+
+At the moment sidebar menu items configuration and Angular 2 Router should be configured independently. We probably will come up with a better solution once new Angular Router is released and stable.
+All menu items are located inside src/app/app.menu.ts file. The file contain a list of Menu Item objects with the following fields:
{
+ title: 'Dashboard', // menu item title
+ component: 'Dashboard', // component where the menu should lead, has a priority over url property
+ url: 'http://google.com' // manual url address (used only when component is not specified)
+ icon: 'ion-android-home', // icon class
+ target: '_blank', // link target attribute (used only when url is specified)
+ selected: false, // is item selected
+ expanded: false, // is item expanded (used only when subItems list specified)
+ order: 0 // order in a list
+ }
+
+You also can define a list of sub-menu items like this:
+ {
+ title: 'Charts',
+ component: 'Charts',
+ icon: 'ion-stats-bars',
+ selected: false,
+ expanded: false,
+ order: 200,
+ subMenu: [ // list of sub-menu items
+ {
+ title: 'Chartist.Js', // sub-item title
+ component: 'ChartistJs' // sum-item component
+ },
+ ]
+ }
+
+Routes configuration is specified in the Page Components according to Angular 2 Router specification. More information you can find here.
+ +Theme Spinner BaThemeSpinner is a small service helper allowing you to show a preloader spinner while executing some long-running tasks.
+Same spinner you can see after reloading a page - it is shown while application is initializing Anuglar 2 and loading charts and images.
The usage interface in quite simple, there are two public methods: show and hide.
Theme Spinner comes with another small helper called BaThemePreloader.
+This service globally integrated into the application and connected to the spinner.
You can register any promise in any part of the application so that the spinner will be hidden only after your promise is completed (resolved).
+You can find an example of usage inside of the app.component.ts file.
+Here we registering a loader (this._imageLoader.load just returns a Promise) which loads a background image:
BaThemePreloader.registerLoader(this._imageLoader.load(layoutPaths.images.root + 'blur-bg-mobile.jpg'));
+
+Then we are starting all the registered promises and once they all are done - hiding the spinner.
+ BaThemePreloader.load().then((values) => {
+ this._spinner.hide();
+ });
+
+You also can register a loader on any page you want. +Say you have a long-running task on the Charts page (you need to receive some data from a web service) and you want the spinner to be shown while the data is loading.
+First thing you need to do is to import BaThemePreloader service:
+ import {BaThemePreloader} from '../../../../theme/services';
+
+Then, say you have a method loading some data called _loadData, in our case we just mocked this method with setTimeout to emulate the loading process:
private _loadData():Promise<any> {
+ return new Promise((resolve, reject) => {
+ setTimeout(() => {
+ resolve();
+ }, 4000);
+ });
+ }
+
+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.
+ +Component-based structure is the best choice for large Angular 2 applications.
+We have put a lot of efforts and carefully selected each color and font for this template!
+Check out our article, where we describe how you can create different look in just 2 minutes!
+Yes, ng2-admin is completely free and MIT licensed. That means you can do with it whatever you want.
+Here's what you can do:
+Yes! We are available for hire. Visit our homepage or simply leave us a note at contact@akveo.com. We will be happy to work with you!
+