Docs v1.1.0  /  Vue.js HTML5 Angular 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.

vue-starter directory structure

vue-starter
build
webpack.static.conf.js
Appwork's stylesheets build config
...
config
src
assets
components
layout
Page layouts
Layout1.vue
Layout1Flex.vue
...
router
Router config
vendor
Appwork's sources
libs
Vue components
vue-color
vue-gallery
...
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
...
App.vue
globals.js
Global properties and methods
...
static
vendor
Appwork's static assets
fonts
js
test
index.html
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 vue-multiselect component, you will need to:

  1. Remove vue-multiselect dependency in the package.json file.
  2. Remove the src/vendor/libs/vue-multiselect directory.
  3. Remove @import "~@/vendor/libs/vue-multiselect/mixins";, @include vue-multiselect-theme($background, $color); and @include material-vue-multiselect-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

index.html
<!DOCTYPE html>

<html lang="en" class="default-style">
  <head>
    <title>Vue 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="/static/vendor/fonts/fontawesome.css"> -->
    <link rel="stylesheet" href="/static/vendor/fonts/ionicons.css">
    <!-- <link rel="stylesheet" href="/static/vendor/fonts/linearicons.css"> -->
    <!-- <link rel="stylesheet" href="/static/vendor/fonts/open-iconic.css"> -->
    <!-- <link rel="stylesheet" href="/static/vendor/fonts/pe-icon-7-stroke.css"> -->

    <!-- Promises -->
    <script src="https://cdnjs.cloudflare.com/ajax/libs/bluebird/3.3.4/bluebird.min.js"></script>

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

  </head>
  <body>

    <div id="app"></div>

    <!-- built files will be auto injected -->
  </body>
</html>
<!DOCTYPE html>

<html lang="en" class="default-style">
  <head>
    <title>Vue 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="/static/vendor/fonts/fontawesome.css"> -->
    <link rel="stylesheet" href="/static/vendor/fonts/ionicons.css">
    <!-- <link rel="stylesheet" href="/static/vendor/fonts/linearicons.css"> -->
    <!-- <link rel="stylesheet" href="/static/vendor/fonts/open-iconic.css"> -->
    <!-- <link rel="stylesheet" href="/static/vendor/fonts/pe-icon-7-stroke.css"> -->

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

    <!-- Promises -->
    <script src="https://cdnjs.cloudflare.com/ajax/libs/bluebird/3.3.4/bluebird.min.js"></script>

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

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

  </head>
  <body>

    <div id="app"></div>

    <!-- built files will be auto injected -->
  </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/layout directory.

src/router/index.js
...

import Layout1 from '@/layout/Layout1'

...

const router = new Router({
  ...

  routes: [{
    ...
  }, {
    path: '/page',
    component: Layout1,
    children: [{
      path: '',
      component: () => import('@/components/Page')
    }]
  }, {
    ...
  }]

  ...
];
src/router/index.js
...

import Layout1Flex from '@/layout/Layout1Flex'

...

const router = new Router({
  ...

  routes: [{
    ...
  }, {
    path: '/page',
    component: Layout1Flex,
    children: [{
      path: '',
      component: () => import('@/components/Page')
    }]
  }, {
    ...
  }]

  ...
];
src/router/index.js
...

import Layout2 from '@/layout/Layout2'

...

const router = new Router({
  ...

  routes: [{
    ...
  }, {
    path: '/page',
    component: Layout2,
    children: [{
      path: '',
      component: () => import('@/components/Page')
    }]
  }, {
    ...
  }]

  ...
];
src/router/index.js
...

import Layout2Flex from '@/layout/Layout2Flex'

...

const router = new Router({
  ...

  routes: [{
    ...
  }, {
    path: '/page',
    component: Layout2Flex,
    children: [{
      path: '',
      component: () => import('@/components/Page')
    }]
  }, {
    ...
  }]

  ...
];
src/router/index.js
...

import LayoutWithoutNavbar from '@/layout/LayoutWithoutNavbar'

...

const router = new Router({
  ...

  routes: [{
    ...
  }, {
    path: '/page',
    component: LayoutWithoutNavbar,
    children: [{
      path: '',
      component: () => import('@/components/Page')
    }]
  }, {
    ...
  }]

  ...
];
src/router/index.js
...

import LayoutWithoutNavbarFlex from '@/layout/LayoutWithoutNavbarFlex'

...

const router = new Router({
  ...

  routes: [{
    ...
  }, {
    path: '/page',
    component: LayoutWithoutNavbarFlex,
    children: [{
      path: '',
      component: () => import('@/components/Page')
    }]
  }, {
    ...
  }]

  ...
];
src/router/index.js
...

import LayoutWithoutSidenav from '@/layout/LayoutWithoutSidenav'

...

const router = new Router({
  ...

  routes: [{
    ...
  }, {
    path: '/page',
    component: LayoutWithoutSidenav,
    children: [{
      path: '',
      component: () => import('@/components/Page')
    }]
  }, {
    ...
  }]

  ...
];
src/router/index.js
...

import LayoutHorizontalSidenav from '@/layout/LayoutHorizontalSidenav'

...

const router = new Router({
  ...

  routes: [{
    ...
  }, {
    path: '/page',
    component: LayoutHorizontalSidenav,
    children: [{
      path: '',
      component: () => import('@/components/Page')
    }]
  }, {
    ...
  }]

  ...
];
src/router/index.js
...

import LayoutBlank from '@/layout/LayoutBlank'

...

const router = new Router({
  ...

  routes: [{
    ...
  }, {
    path: '/page',
    component: LayoutBlank,
    children: [{
      path: '',
      component: () => import('@/components/Page')
    }]
  }, {
    ...
  }]

  ...
];

Appwork's stylesheets

To use settings panel, you need to enable Appwork's stylesheets compilation (use the generator to see the example):

  1. Open src/App.vue file and remove all Appwork's SCSS imports.
  2. Open the build/webpack.dev.conf.js file and change module.exports assignment so that you return Promise.all:

    module.exports = Promise.all([
      new Promise((resolve, reject) => {
        ...
      }),
      require('./webpack.static.conf')
    ])
  3. Open the build/webpack.prod.conf.js file and change module.exports assignment to:

    module.exports = [webpackConfig, require('./webpack.static.conf')]

Theming

To enable a theme, import theme SCSS file in the src/App.vue file.

src/App.vue
<style src="@/vendor/styles/theme-air.scss" lang="scss"></style>

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

index.html
<link rel="stylesheet" href="/static/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.

    index.html
    <html class="material-style">
  2. Add -material suffix to bootstrap.scss, appwork.scss, theme-*.scss and colors.scss imports in the src/App.vue file.

    src/App.vue
    <style src="@/vendor/styles/bootstrap-material.scss" lang="scss"></style>
    <style src="@/vendor/styles/appwork-material.scss" lang="scss"></style>
    <style src="@/vendor/styles/theme-corporate-material.scss" lang="scss"></style>
    <style src="@/vendor/styles/colors-material.scss" lang="scss"></style>
  3. Add -material suffix to bootstrap, appwork, theme-* and colors stylesheets.

    index.html
    <link rel="stylesheet" href="/static/vendor/styles/bootstrap-material.css" class="theme-settings-bootstrap-css">
    <link rel="stylesheet" href="/static/vendor/styles/appwork-material.css" class="theme-settings-appwork-css">
    <link rel="stylesheet" href="/static/vendor/styles/theme-corporate-material.css" class="theme-settings-theme-css">
    <link rel="stylesheet" href="/static/vendor/styles/colors-material.css" class="theme-settings-colors-css">
  4. Optionally you can enable material ripple. Just append material-ripple.js script to the <head> section and call attachMaterialRippleOnLoad() function.

    index.html
    <script src="/static/vendor/js/material-ripple.js"></script>
    <script>
      window.attachMaterialRippleOnLoad();
    </script>
  5. Optionally you can enable material ripple. Just append material-ripple.js script to the <head> section.

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

RTL support

To enable RTL direction support, import Appwork's SCSS files from the vendor/styles/rtl/ directory instead of vendor/styles/.

src/App.vue
<style src="@/vendor/styles/rtl/bootstrap.scss" lang="scss"></style>
<style src="@/vendor/styles/rtl/appwork.scss" lang="scss"></style>
<style src="@/vendor/styles/rtl/theme-corporate.scss" lang="scss"></style>
<style src="@/vendor/styles/rtl/colors.scss" lang="scss"></style>
<style src="@/vendor/styles/rtl/uikit.scss" lang="scss"></style>

To enable RTL direction support, open build/webpack.static.conf.js file and edit paths to load Appwork's SCSS from the src/vendor/styles/rtl/ directory instead of src/vendor/styles/.

build/webpack.static.conf.js
...

const webpackConfig = {
  entry: {
    'bootstrap': './src/vendor/styles/rtl/bootstrap.scss',
    'bootstrap-material': './src/vendor/styles/rtl/bootstrap-material.scss',
    'appwork': './src/vendor/styles/rtl/appwork.scss',
    'appwork-material': './src/vendor/styles/rtl/appwork-material.scss',
    ...
  },
  ...
}

...

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.

Generator

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

Available tasks

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

Task Description
dev Run dev server.
build Build for production. Please note that output stylesheets within static/vendor/styles/ directory will not have a hash in their filenames. So you will need to define caching strategy for these files by yourself.
unit Run unit tests.
e2e Run end-to-end tests.
test Run unit and end-to-end tests.
lint Run linting.