Docs v1.1.0  /  Angular HTML5 Vue.js Laravel Laravel + Vue.js Rails ASP.NET Core 2 ASP.NET MVC
OTHER
Settings panel Layout helpers

Instructions can vary depending on whatever you use theme settings panel or not. Please select the appropriate version.

angular-starter directory structure

angular-starter
e2e
End-to-end tests
src
app
layout
Page layouts
layout-1
layout-1-flex
...
app.component.ts
app.module.ts
...
assets
vendor
Appwork's static assets
fonts
js
environments
vendor
Appwork's sources
libs
Angular components
angular-2-dropdown-multiselect
angular2-ladda
...
styles
SCSS sources
_appwork
Appwork includes
_custom-variables
Custom variables
_theme
Theme includes
_uikit
UIKit includes
pages
Page styles
rtl
Styles with RTL support enabled
appwork.scss
appwork-material.scss
...
index.html
main.ts
...
angular.json
package.json
...

Third-party components

The starter project by default includes all third-party components.
Optionally you can remove unwanted components to reduce bundle size and compile time:

  1. Remove unwanted packages from the dependencies section in the package.json file.
  2. Remove related directories within the src/vendor/libs directory.
  3. Remove related @imports and @includes in the src/vendor/styles/_theme/_libs.scss file.

For example, if you want to exclude ng-select component, you will need to:

  1. Remove ng-select dependency in the package.json file.
  2. Remove the src/vendor/libs/ng-select directory.
  3. Remove @import "~vendor/libs/ng-select/mixins";, @include ng-select-theme($background, $color); and @include material-ng-select-theme($background, $color); lines in the src/vendor/styles/_theme/_libs.scss file.

Installation

Windows
  1. Download and install Node.js 8.x from https://nodejs.org/en/.
  2. Download and install Git from https://git-scm.com/downloads.
  3. Download and install Yarn from https://yarnpkg.com/en/docs/install.
  4. Logout from the system and login again.
  5. Launch cmd.exe as administrator and run command npm install --add-python-to-path='true' --global --production windows-build-tools.
  6. Logout from the system and login again.
  7. Open cmd.exe, go to the angular-starter directory and run command yarn install.
Ubuntu
  1. Upgrade system: sudo apt-get update && sudo apt-get upgrade.
  2. Install curl: sudo apt-get install curl.
  3. Install Node.js 8.x and build tools following instructions on https://nodejs.org/en/download/package-manager/#debian-and-ubuntu-based-linux-distributions.
  4. Install Git following instructions on https://git-scm.com/download/linux.
  5. Install Yarn following instructions on https://yarnpkg.com/en/docs/install#debian-stable.
  6. Open terminal, go to the angular-starter directory and run command yarn install.
Mac OS X
  1. Install Xcode from App Store. After installing, launch the Xcode, accept the license agreement and wait while components installed.
  2. Install Homebrew following instructions on https://brew.sh.
  3. Download and install Node.js 8.x from https://nodejs.org/en/.
  4. Download and install Git from https://git-scm.com/downloads.
  5. Install Yarn following instructions on https://yarnpkg.com/en/docs/install.
  6. Open terminal, go to the angular-starter directory and run command yarn install.

Page structure

Instead of configuring the layout manually, you can use the Starter template generator. It will dramatically simplify the initial setup.

index.html

src/index.html
<!DOCTYPE html>

<html lang="en" class="default-style">
  <head>
    <base href="/">
    <title>Angular Starter</title>

    <meta charset="utf-8">
    <meta http-equiv="x-ua-compatible" content="IE=edge,chrome=1">
    <meta name="description" content="">
    <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
    <link rel="icon" type="image/x-icon" href="favicon.ico">

    <!-- Main font -->
    <link href="https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,500,500i,700,700i,900" rel="stylesheet">

    <!-- Icons. Uncomment required icon fonts -->
    <!-- <link rel="stylesheet" href="assets/vendor/fonts/fontawesome.css"> -->
    <link rel="stylesheet" href="assets/vendor/fonts/ionicons.css">
    <!-- <link rel="stylesheet" href="assets/vendor/fonts/linearicons.css"> -->
    <!-- <link rel="stylesheet" href="assets/vendor/fonts/open-iconic.css"> -->
    <!-- <link rel="stylesheet" href="assets/vendor/fonts/pe-icon-7-stroke.css"> -->

    <!-- Layout helpers -->
    <script src="assets/vendor/js/layout-helpers.js"></script>

  </head>
  <body>

    <!-- App root -->
    <app-root></app-root>
    <!-- / App root -->

    <!-- IE11 fix -->
    <script>
    if (!!window.MSInputMethodContext && !!document.documentMode || document.documentMode <= 11) {
      window.MouseEvent.prototype = Event.prototype;

      window.MouseEvent = function (eventType, params) {
        params = params || { bubbles: false, cancelable: false };
        var mouseEvent = document.createEvent('MouseEvent');
        mouseEvent.initMouseEvent(eventType, params.bubbles, params.cancelable, window, 0, 0, 0, 0, 0, false, false, false, false, 0, null);

        return mouseEvent;
      }
    }
    </script>
  </body>
</html>
<!DOCTYPE html>

<html lang="en" class="default-style">
  <head>
    <base href="/">
    <title>Angular Starter</title>

    <meta charset="utf-8">
    <meta http-equiv="x-ua-compatible" content="IE=edge,chrome=1">
    <meta name="description" content="">
    <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
    <link rel="icon" type="image/x-icon" href="favicon.ico">

    <!-- Main font -->
    <link href="https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,500,500i,700,700i,900" rel="stylesheet">

    <!-- Icons. Uncomment required icon fonts -->
    <!-- <link rel="stylesheet" href="assets/vendor/fonts/fontawesome.css"> -->
    <link rel="stylesheet" href="assets/vendor/fonts/ionicons.css">
    <!-- <link rel="stylesheet" href="assets/vendor/fonts/linearicons.css"> -->
    <!-- <link rel="stylesheet" href="assets/vendor/fonts/open-iconic.css"> -->
    <!-- <link rel="stylesheet" href="assets/vendor/fonts/pe-icon-7-stroke.css"> -->

    <!-- Core stylesheets -->
    <link rel="stylesheet" href="vendor/styles/bootstrap.css" class="theme-settings-bootstrap-css">
    <link rel="stylesheet" href="vendor/styles/appwork.css" class="theme-settings-appwork-css">
    <link rel="stylesheet" href="vendor/styles/theme-corporate.css" class="theme-settings-theme-css">
    <link rel="stylesheet" href="vendor/styles/colors.css" class="theme-settings-colors-css">
    <link rel="stylesheet" href="vendor/styles/uikit.css">

    <!-- Layout helpers -->
    <script src="assets/vendor/js/layout-helpers.js"></script>

    <!-- Theme settings -->
    <script src="assets/vendor/js/theme-settings.js"></script>
    <script>
      window.themeSettings = new ThemeSettings({
        cssPath: 'vendor/styles/',
        themesPath: 'vendor/styles/'
      });
    </script>

  </head>
  <body>

    <!-- App root -->
    <app-root></app-root>
    <!-- / App root -->

    <!-- IE11 fix -->
    <script>
    if (!!window.MSInputMethodContext && !!document.documentMode || document.documentMode <= 11) {
      window.MouseEvent.prototype = Event.prototype;

      window.MouseEvent = function (eventType, params) {
        params = params || { bubbles: false, cancelable: false };
        var mouseEvent = document.createEvent('MouseEvent');
        mouseEvent.initMouseEvent(eventType, params.bubbles, params.cancelable, window, 0, 0, 0, 0, 0, false, false, false, false, 0, null);

        return mouseEvent;
      }
    }
    </script>
  </body>
</html>

Layouts

To display a page with the selected layout just define the page component as a child of the layout component.

You can find navbar, sidenav and footer components in the src/app/layout/layout-navbar, src/app/layout/layout-sidenav and src/app/layout/layout-footer directories. 

src/app/app-routing.module.ts
...

import { Layout1Component } from './layout/layout-1/layout-1.component';

...

const routes: Routes = [
  ...

  { path: '/page', component: Layout1Component, children: [
    { path: '', component: PageComponent },
  ]},

  ...
];
src/app/app-routing.module.ts
...

import { Layout1FlexComponent } from './layout/layout-1-flex/layout-1-flex.component';

...

const routes: Routes = [
  ...

  { path: '/page', component: Layout1FlexComponent, children: [
    { path: '', component: PageComponent },
  ]},

  ...
];
src/app/app-routing.module.ts
...

import { Layout2Component } from './layout/layout-2/layout-2.component';

...

const routes: Routes = [
  ...

  { path: '/page', component: Layout2Component, children: [
    { path: '', component: PageComponent },
  ]},

  ...
];
src/app/app-routing.module.ts
...

import { Layout2FlexComponent } from './layout/layout-2-flex/layout-2-flex.component';

...

const routes: Routes = [
  ...

  { path: '/page', component: Layout2FlexComponent, children: [
    { path: '', component: PageComponent },
  ]},

  ...
];
src/app/app-routing.module.ts
...

import { LayoutWithoutNavbarComponent } from './layout/layout-without-navbar/layout-without-navbar.component';

...

const routes: Routes = [
  ...

  { path: '/page', component: LayoutWithoutNavbarComponent, children: [
    { path: '', component: PageComponent },
  ]},

  ...
];
src/app/app-routing.module.ts
...

import { LayoutWithoutNavbarFlexComponent } from './layout/layout-without-navbar-flex/layout-without-navbar-flex.component';

...

const routes: Routes = [
  ...

  { path: '/page', component: LayoutWithoutNavbarFlexComponent, children: [
    { path: '', component: PageComponent },
  ]},

  ...
];
src/app/app-routing.module.ts
...

import { LayoutWithoutSidenavComponent } from './layout/layout-without-sidenav/layout-without-sidenav.component';

...

const routes: Routes = [
  ...

  { path: '/page', component: LayoutWithoutSidenavComponent, children: [
    { path: '', component: PageComponent },
  ]},

  ...
];
src/app/app-routing.module.ts
...

import { LayoutHorizontalSidenavComponent } from './layout/layout-horizontal-sidenav/layout-horizontal-sidenav.component';

...

const routes: Routes = [
  ...

  { path: '/page', component: LayoutHorizontalSidenavComponent, children: [
    { path: '', component: PageComponent },
  ]},

  ...
];
src/app/app-routing.module.ts
...

import { LayoutBlankComponent } from './layout/layout-blank/layout-blank.component';

...

const routes: Routes = [
  ...

  { path: '/page', component: LayoutBlankComponent, children: [
    { path: '', component: PageComponent },
  ]},

  ...
];

angular.json

To use settings panel, you need to make Appwork's stylesheets separated from application stylesheets (use the generator to see the example):

  1. Open angular.json file and remove all Appwork's SCSS paths within projects.angular-starter.architect.build.options.styles section.

  2. Add imports using lazy notation:

    angular.json
    ...

"styles": [
  ...
  { "input": "src/vendor/styles/appwork.scss", "bundleName": "vendor/styles/appwork", "lazy": true },
  { "input": "src/vendor/styles/appwork-material.scss", "bundleName": "vendor/styles/appwork-material", "lazy": true },
  { "input": "src/vendor/styles/bootstrap.scss", "bundleName": "vendor/styles/bootstrap", "lazy": true },
  { "input": "src/vendor/styles/bootstrap-material.scss", "bundleName": "vendor/styles/bootstrap-material", "lazy": true },
  ...
],

...

Theming

To enable a theme, insert path to a theme SCSS file into the projects.angular-starter.architect.build.options.styles section of angular.json file. Do not forget to remove the old theme path. All files within this section will be included into the <head> section automatically. 

angular.json
...

"styles": [
  ...
  "src/vendor/styles/theme-air.scss",
  ...
],

...

To enable a theme, include the required theme stylesheet from the vendor/styles/ path.

src/index.html
<link rel="stylesheet" href="vendor/styles/theme-air.css" class="theme-settings-theme-css">

Material styling

To enable material styling you need to:

  1. Set material-style class on the <html> element instead of default-style.

    src/index.html
    <html class="material-style">

  2. Add -material suffix to bootstrap.scss, appwork.scss, theme-*.scss and colors.scss paths within projects.angular-starter.architect.build.options.styles section of angular.json file. 

    angular.json
    ...

"styles": [
  ...
  "src/vendor/styles/bootstrap-material.scss",
  "src/vendor/styles/appwork-material.scss",
  "src/vendor/styles/theme-corporate-material.scss",
  "src/vendor/styles/colors-material.scss",
  ...
],

...

    Add -material suffix to bootstrap, appwork, theme-* and colors stylesheets. 

    src/index.html
    <link rel="stylesheet" href="vendor/styles/bootstrap-material.css" class="theme-settings-bootstrap-css">
<link rel="stylesheet" href="vendor/styles/appwork-material.css" class="theme-settings-appwork-css">
<link rel="stylesheet" href="vendor/styles/theme-corporate-material.css" class="theme-settings-theme-css">
<link rel="stylesheet" href="vendor/styles/colors-material.css" class="theme-settings-colors-css">

  3. Optionally you can enable material ripple. Just append material-ripple.js script to the <head> section and call attachMaterialRippleOnLoad() function. 

    src/index.html
    <script src="assets/vendor/js/material-ripple.js"></script>
<script>
  window.attachMaterialRippleOnLoad();
</script>

  4. Optionally you can enable material ripple. Just append material-ripple.js script to the <head> section. 

    src/index.html
    <script src="assets/vendor/js/material-ripple.js"></script>

RTL support

To enable RTL direction support, include SCSS files from the src/vendor/styles/rtl/ directory instead of src/vendor/styles/ within projects.angular-starter.architect.build.options.styles section of angular.json file. 

angular.json
...

"styles": [
  ...
  "src/vendor/styles/rtl/bootstrap.scss",
  "src/vendor/styles/rtl/appwork.scss",
  "src/vendor/styles/rtl/theme-corporate.scss",
  "src/vendor/styles/rtl/colors.scss",
  "src/vendor/styles/rtl/uikit.scss"
  ...
],

...

To enable RTL direction support, include SCSS files from the src/vendor/styles/rtl/ directory instead of src/vendor/styles/ within projects.angular-starter.architect.build.options.styles section of angular.json file. 

angular.json
...

"styles": [
  ...
  { "input": "src/vendor/styles/rtl/appwork.scss", "bundleName": "vendor/styles/appwork", "lazy": true },
  { "input": "src/vendor/styles/rtl/appwork-material.scss", "bundleName": "vendor/styles/appwork-material", "lazy": true },
  { "input": "src/vendor/styles/rtl/bootstrap.scss", "bundleName": "vendor/styles/bootstrap", "lazy": true },
  { "input": "src/vendor/styles/rtl/bootstrap-material.scss", "bundleName": "vendor/styles/bootstrap-material", "lazy": true },
  ...
],

...

To enable RTL direction, add dir="rtl" attribute to the <html> element.

src/index.html
<html dir="rtl">

Layout options

You can configure the initial layout by setting control classes to the <html> element.

After the initial layout setup the recommended way to control layout options is layout helpers, because the helpers do some extra work, such as: setting container paddings (when navbar is fixed), performing layout animations, setting correct sidenav state classes depending on screen size etc. 
src/index.html
<html class="layout-fixed layout-collapsed">
Control class Description
.layout-reversed Reverse layout direction without markup change.
.layout-expanded Expand layout sidenav on small screens (< 992px).
.layout-collapsed Collapse layout sidenav on large screens (>= 992px).
.layout-offcanvas Make layout sidenav offcanvas.
.layout-fixed Set layout position to fixed.
.layout-fixed-offcanvas Set layout position to fixed with offcanvas sidenav.
.layout-navbar-fixed Set layout navbar position to fixed.
.layout-footer-fixed Set layout footer position to fixed.

Generator

Use starter template generator to simplify the initial setup. Just replace a content of appropriate files with the generated code within the angular-starter directory.

Open in new tab

Available tasks

Open console/terminal, go to the angular-starter directory and run npm run task_name.

Task Description
ng Run angular-cli's ng command.
start Run dev server.
build Build.
prod Build for production. Output files won't contain hash in their filenames.
prod:hashed Build for production. Output files will contain hash in their filenames.
test Run unit tests.
lint Run linting.
e2e Run end-to-end tests.

Build for production

To build the project for production just run prod:hashed command.

There are two ways to build the project for production:

  1. Use prod command. This command generates output files without hash in their names. You will need to define a caching strategy for these files by yourself.
  2. Use prod:hashed command. This command generates output files with hash in their names. But currently angular-cli does not provide the ability to get a hash map for lazy loaded stylesheets. So you will need to write your own post build script that will scan vendor/styles directory, find all hashed stylesheets and fix urls for theese stylesheets in the index.html file.