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

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

html-starter directory structure

html-starter
assets
js
Application javascripts
vendor
Appwork's assets
js
Javascripts
bootstrap.js
...
css
Stylesheets
pages
Pages styling
rtl
Stylesheets with RTL support
bootstrap.css
appwork.css
...
fonts
Iconic fonts
libs
Third-party libraries
animate-css
autosize
block-ui
...
index.html
...

Page structure

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

Main

index.html
<!DOCTYPE html>

<html lang="en" class="default-style">
<head>
  <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">

  <title>TITLE</title>

  <!-- 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="assets/vendor/css/bootstrap.css">
  <link rel="stylesheet" href="assets/vendor/css/appwork.css">
  <link rel="stylesheet" href="assets/vendor/css/theme-corporate.css">
  <link rel="stylesheet" href="assets/vendor/css/colors.css">
  <link rel="stylesheet" href="assets/vendor/css/uikit.css">

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

  <!-- Libs -->

  <!-- `perfect-scrollbar` library required by SideNav plugin -->
  <link rel="stylesheet" href="assets/vendor/libs/perfect-scrollbar/perfect-scrollbar.css">

</head>
<body>

  CONTENT

  <!-- Core scripts -->

  <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.2.1/jquery.min.js"></script>
  <script src="assets/vendor/libs/popper/popper.js"></script>
  <script src="assets/vendor/js/bootstrap.js"></script>
  <script src="assets/vendor/js/sidenav.js"></script>

  <!-- Libs -->

  <!-- `perfect-scrollbar` library required by SideNav plugin -->
  <script src="assets/vendor/libs/perfect-scrollbar/perfect-scrollbar.js"></script>

</body>
</html>
index.html
<!DOCTYPE html>

<html lang="en" class="default-style">
<head>
  <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">

  <title>TITLE</title>

  <!-- 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="assets/vendor/css/bootstrap.css" class="theme-settings-bootstrap-css">
  <link rel="stylesheet" href="assets/vendor/css/appwork.css" class="theme-settings-appwork-css">
  <link rel="stylesheet" href="assets/vendor/css/theme-corporate.css" class="theme-settings-theme-css">
  <link rel="stylesheet" href="assets/vendor/css/colors.css" class="theme-settings-colors-css">
  <link rel="stylesheet" href="assets/vendor/css/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: 'assets/vendor/css/',
      themesPath: 'assets/vendor/css/'
    });
  </script>

  <!-- Libs -->

  <!-- `perfect-scrollbar` library required by SideNav plugin -->
  <link rel="stylesheet" href="assets/vendor/libs/perfect-scrollbar/perfect-scrollbar.css">

</head>
<body>

  CONTENT

  <!-- Core scripts -->

  <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.2.1/jquery.min.js"></script>
  <script src="assets/vendor/libs/popper/popper.js"></script>
  <script src="assets/vendor/js/bootstrap.js"></script>
  <script src="assets/vendor/js/sidenav.js"></script>

  <!-- Libs -->

  <!-- `perfect-scrollbar` library required by SideNav plugin -->
  <script src="assets/vendor/libs/perfect-scrollbar/perfect-scrollbar.js"></script>

</body>
</html>

Layouts

<!-- Layout wrapper -->
<div class="layout-wrapper layout-1">
  <!-- Layout inner -->
  <div class="layout-inner">

    <!-- Layout navbar -->
    <nav class="layout-navbar navbar navbar-expand-lg align-items-lg-center bg-navbar-theme container-p-x" id="layout-navbar">
      NAVBAR CONTENT
    </nav>
    <!-- / Layout navbar -->

    <div class="layout-container">

      <!-- Layout sidenav -->
      <div id="layout-sidenav" class="layout-sidenav sidenav sidenav-vertical bg-sidenav-theme">
        SIDENAV CONTENT
      </div>
      <!-- / Layout sidenav -->

      <div class="layout-content">

        <!-- Page content -->
        <div class="container-fluid flex-grow-1 container-p-y">
          PAGE CONTENT
        </div>
        <!-- / Page content -->

        <!-- Layout footer -->
        <nav class="layout-footer footer bg-footer-theme">
          FOOTER CONTENT
        </nav>
        <!-- / Layout footer -->

      </div>
    </div>

  </div>
  <!-- Layout inner -->

  <div class="layout-overlay layout-sidenav-toggle"></div>
</div>
<!-- / Layout wrapper -->
<!-- Layout wrapper -->
<div class="layout-wrapper layout-1">
  <!-- Layout inner -->
  <div class="layout-inner">

    <!-- Layout navbar -->
    <nav class="layout-navbar navbar navbar-expand-lg align-items-lg-center bg-navbar-theme container-p-x" id="layout-navbar">
      NAVBAR CONTENT
    </nav>
    <!-- / Layout navbar -->

    <div class="layout-container">

      <!-- Layout sidenav -->
      <div id="layout-sidenav" class="layout-sidenav sidenav sidenav-vertical bg-sidenav-theme">
        SIDENAV CONTENT
      </div>
      <!-- / Layout sidenav -->

      <div class="layout-content">

        <!-- Page content -->
        <div class="container-fluid flex-grow-1 d-flex align-items-stretch p-0">
          PAGE CONTENT
        </div>
        <!-- / Page content -->

        <!-- Layout footer -->
        <nav class="layout-footer footer bg-footer-theme">
          FOOTER CONTENT
        </nav>
        <!-- / Layout footer -->

      </div>
    </div>

  </div>
  <!-- Layout inner -->

  <div class="layout-overlay layout-sidenav-toggle"></div>
</div>
<!-- / Layout wrapper -->
<!-- Layout wrapper -->
<div class="layout-wrapper layout-2">
  <!-- Layout inner -->
  <div class="layout-inner">

    <!-- Layout sidenav -->
    <div id="layout-sidenav" class="layout-sidenav sidenav sidenav-vertical bg-sidenav-theme">
      SIDENAV CONTENT
    </div>
    <!-- / Layout sidenav -->

    <div class="layout-container">

      <!-- Layout navbar -->
      <nav class="layout-navbar navbar navbar-expand-lg align-items-lg-center bg-navbar-theme container-p-x" id="layout-navbar">
        NAVBAR CONTENT
      </nav>
      <!-- / Layout navbar -->

      <div class="layout-content">

        <!-- Page content -->
        <div class="container-fluid flex-grow-1 container-p-y">
          PAGE CONTENT
        </div>
        <!-- / Page content -->

        <!-- Layout footer -->
        <nav class="layout-footer footer bg-footer-theme">
          FOOTER CONTENT
        </nav>
        <!-- / Layout footer -->

      </div>
    </div>

  </div>
  <!-- Layout inner -->

  <div class="layout-overlay layout-sidenav-toggle"></div>
</div>
<!-- / Layout wrapper -->
<!-- Layout wrapper -->
<div class="layout-wrapper layout-2">
  <!-- Layout inner -->
  <div class="layout-inner">

    <!-- Layout sidenav -->
    <div id="layout-sidenav" class="layout-sidenav sidenav sidenav-vertical bg-sidenav-theme">
      SIDENAV CONTENT
    </div>
    <!-- / Layout sidenav -->

    <div class="layout-container">

      <!-- Layout navbar -->
      <nav class="layout-navbar navbar navbar-expand-lg align-items-lg-center bg-navbar-theme container-p-x" id="layout-navbar">
        NAVBAR CONTENT
      </nav>
      <!-- / Layout navbar -->

      <div class="layout-content">

        <!-- Page content -->
        <div class="container-fluid flex-grow-1 d-flex align-items-stretch p-0">
          PAGE CONTENT
        </div>
        <!-- / Page content -->

        <!-- Layout footer -->
        <nav class="layout-footer footer bg-footer-theme">
          FOOTER CONTENT
        </nav>
        <!-- / Layout footer -->

      </div>
    </div>

  </div>
  <!-- Layout inner -->

  <div class="layout-overlay layout-sidenav-toggle"></div>
</div>
<!-- / Layout wrapper -->
<!-- Layout wrapper -->
<div class="layout-wrapper layout-1">
  <!-- Layout inner -->
  <div class="layout-inner">

    <div class="layout-container">

      <!-- Layout sidenav -->
      <div id="layout-sidenav" class="layout-sidenav sidenav sidenav-vertical bg-sidenav-theme">
        SIDENAV CONTENT
      </div>
      <!-- / Layout sidenav -->

      <div class="layout-content">

        <!-- Page content -->
        <div class="container-fluid flex-grow-1 container-p-y">
          PAGE CONTENT
        </div>
        <!-- / Page content -->

        <!-- Layout footer -->
        <nav class="layout-footer footer bg-footer-theme">
          FOOTER CONTENT
        </nav>
        <!-- / Layout footer -->

      </div>
    </div>

  </div>
  <!-- Layout inner -->

  <div class="layout-overlay layout-sidenav-toggle"></div>
</div>
<!-- / Layout wrapper -->
<!-- Layout wrapper -->
<div class="layout-wrapper layout-1">
  <!-- Layout inner -->
  <div class="layout-inner">

    <div class="layout-container">

      <!-- Layout sidenav -->
      <div id="layout-sidenav" class="layout-sidenav sidenav sidenav-vertical bg-sidenav-theme">
        SIDENAV CONTENT
      </div>
      <!-- / Layout sidenav -->

      <div class="layout-content">

        <!-- Page content -->
        <div class="container-fluid flex-grow-1 d-flex align-items-stretch p-0">
          PAGE CONTENT
        </div>
        <!-- / Page content -->

        <!-- Layout footer -->
        <nav class="layout-footer footer bg-footer-theme">
          FOOTER CONTENT
        </nav>
        <!-- / Layout footer -->

      </div>
    </div>

  </div>
  <!-- Layout inner -->

  <div class="layout-overlay layout-sidenav-toggle"></div>
</div>
<!-- / Layout wrapper -->
<!-- Layout wrapper -->
<div class="layout-wrapper layout-1 layout-without-sidenav">
  <!-- Layout inner -->
  <div class="layout-inner">

    <!-- Layout navbar -->
    <nav class="layout-navbar navbar navbar-expand-lg align-items-lg-center bg-navbar-theme container-p-x" id="layout-navbar">
      NAVBAR CONTENT
    </nav>
    <!-- / Layout navbar -->

    <div class="layout-container">

      <div class="layout-content">

        <!-- Page content -->
        <div class="container-fluid flex-grow-1 container-p-y">
          PAGE CONTENT
        </div>
        <!-- / Page content -->

        <!-- Layout footer -->
        <nav class="layout-footer footer bg-footer-theme">
          FOOTER CONTENT
        </nav>
        <!-- / Layout footer -->

      </div>
    </div>

  </div>
  <!-- Layout inner -->
</div>
<!-- / Layout wrapper -->
<!-- Layout wrapper -->
<div class="layout-wrapper layout-1 layout-without-sidenav">
  <!-- Layout inner -->
  <div class="layout-inner">

    <!-- Layout navbar -->
    <nav class="layout-navbar navbar navbar-expand-lg align-items-lg-center bg-navbar-theme container-p-x" id="layout-navbar">
      NAVBAR CONTENT
    </nav>
    <!-- / Layout navbar -->

    <div class="layout-container">

      <div class="layout-content">

        <!-- Layout sidenav -->
        <div id="layout-sidenav" class="layout-sidenav-horizontal sidenav sidenav-horizontal bg-sidenav-theme container-p-x flex-grow-0">
          SIDENAV CONTENT
        </div>
        <!-- / Layout sidenav -->

        <!-- Page content -->
        <div class="container-fluid flex-grow-1 container-p-y">
          PAGE CONTENT
        </div>
        <!-- / Page content -->

        <!-- Layout footer -->
        <nav class="layout-footer footer bg-footer-theme">
          FOOTER CONTENT
        </nav>
        <!-- / Layout footer -->

      </div>
    </div>

  </div>
  <!-- Layout inner -->
</div>
<!-- / Layout wrapper -->

Theming

To enable theme just include the required theme stylesheet from the vendor/css/ path.

index.html
<link rel="stylesheet" href="assets/vendor/css/theme-air.css">
<link rel="stylesheet" href="assets/vendor/css/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.

    index.html
    <html class="material-style">
  2. Add -material suffix to bootstrap.css, appwork.css, theme-*.css and colors.css stylesheets.

    index.html
    <link rel="stylesheet" href="assets/vendor/css/bootstrap-material.css">
    <link rel="stylesheet" href="assets/vendor/css/appwork-material.css">
    <link rel="stylesheet" href="assets/vendor/css/theme-corporate-material.css">
    <link rel="stylesheet" href="assets/vendor/css/colors-material.css">
    <link rel="stylesheet" href="assets/vendor/css/bootstrap-material.css" class="theme-settings-bootstrap-css">
    <link rel="stylesheet" href="assets/vendor/css/appwork-material.css" class="theme-settings-appwork-css">
    <link rel="stylesheet" href="assets/vendor/css/theme-corporate-material.css" class="theme-settings-theme-css">
    <link rel="stylesheet" href="assets/vendor/css/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.

    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.

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

RTL support

To enable RTL direction support just load Appwork's stylesheets from the vendor/css/rtl/ path instead of vendor/css/.

index.html
<link rel="stylesheet" href="assets/vendor/css/rtl/bootstrap.css">
<link rel="stylesheet" href="assets/vendor/css/rtl/appwork.css">
<link rel="stylesheet" href="assets/vendor/css/rtl/theme-corporate.css">
<link rel="stylesheet" href="assets/vendor/css/rtl/colors.css">
<link rel="stylesheet" href="assets/vendor/css/rtl/uikit.css">
<link rel="stylesheet" href="assets/vendor/css/rtl/bootstrap.css" class="theme-settings-bootstrap-css">
<link rel="stylesheet" href="assets/vendor/css/rtl/appwork.css" class="theme-settings-appwork-css">
<link rel="stylesheet" href="assets/vendor/css/rtl/theme-corporate.css" class="theme-settings-theme-css">
<link rel="stylesheet" href="assets/vendor/css/rtl/colors.css" class="theme-settings-colors-css">
<link rel="stylesheet" href="assets/vendor/css/rtl/uikit.css">

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

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.
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.

PACE.js progress

Optionally you can enable PACE.js progress bar:

  1. Append pace.js script to the <head> section.

    index.html
    <script src="assets/vendor/js/pace.js"></script>
  2. Append .page-loader element to the <body>.

    index.html
    <div class="page-loader"><div class="bg-primary"></div></div>

Generator

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

Sources

src directory structure

src
css
CSS 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
...
fonts
Iconic fonts
fontawesome.scss
ionicons.scss
...
js
Javascript sources
bootstrap.es6
dropdown-hover.es6
...
libs
Third-party libraries
animate-css
autosize
block-ui
...
build-config.js
Build config
gulpfile.js
Gulp tasks
webpack.config.js
Webpack config
...

Third-party plugins

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

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

For example, if you want to exclude plyr plugin, you will need to:

  1. Remove plyr dependency in the src/package.json file.
  2. Remove the src/libs/plyr directory.
  3. Remove @import "../../libs/plyr/mixins"; and @include plyr-theme($background, $color); lines in the src/css/_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 src directory and run command yarn install --ignore-engines.
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 src directory and run command yarn install --ignore-engines.
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 src directory and run command yarn install --ignore-engines.

Build

Appwork's build system is a simple but powerful solution:

  • Uses Webpack + Babel for compilation. So you can use all Webpack features (such as requiring scripts) and write your code using the ES6 specification.
  • Simple SCSS compilation without any wrappers.
  • The output directory structure will repeat the source directory structure.
  • Automatically discovers .scss, .js and .es6 files to compile. To exclude a file from compilation list just prepend a _ symbol to the filename.
  • Automatically copies images and font files.
  • Easy to configure - just edit build-config.js file.
  • Development and production environments. To add environment edit gulp-environment.environments section within package.json file.
  • Easy to extend the build system by adding new Gulp/Webpack tasks.

Example

Let's assume that src directory have the next structure:

src
stylesheets
components
dropdown.scss
includes
components
_dropdown-item.scss
_mixins.scss
_common.scss
_variables.scss
main.scss
javascripts
components
_dropdown-item.es6
dropdown.es6
utils
html
_elements.es6
_selectors.es6
http
_ajax.es6
_serializer.es6
utils.es6
_config.js
common.js
images
logo.png
site.scss
site.js

The output directory will have the next structure:

dist
stylesheets
components
dropdown.css
main.css
javascripts
components
dropdown.js
utils
utils.js
common.js
images
logo.png
site.css
site.js

When you execute build task the next actions will be performed:

  1. Read build config options from build-config.js. The options can vary depending on the current environment.
  2. Run clean task if cleanBuild option is enabled.
  3. Run the next gulp tasks in parallel:
    • build:css - Runs SCSS compiltion for each file which filename is not starting with a _ symbol.
    • build:js - Collects all .es6 and .js files which filename is not starting with a _ symbol. Then performs compilation via Webpack and Babel. All files are processed as separate entries.
    • build:fonts - Copies font files(that defined in the gulpfile) from node_modules.
    • build:copy - Copies images and other font files

Available tasks

Open console/terminal, go to the src directory and run npm run task_name. To run a task with specified environment just execute the task with --env=environment option, e.g. npm run build --env=production.

Task Description
build Compile sources and copy assets.
build:js Compile javascript sources.
build:css Compile SCSS sources.
build:fonts Copy fonts that defined in the gulpfile.
build:copy Copy images and other font files.
build:prod Run build task in production environment.
build:prod:js Run build:js task in production environment.
build:prod:css Run build:css task in production environment.
build:prod:fonts Run build:fonts task in production environment.
build:prod:copy Run build:copy task in production environment.
watch Watch files for changes and automatically recompile it when changed.