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

rails-starter directory structure

rails-starter
app
assets
channels
controllers
helpers
jobs
mailers
models
views
layouts
main
Page layouts
layout-1.html.erb
layout-1-flex.html.erb
...
partials
Layout partials
_layout-footer.html.erb
_layout-navbar.html.erb
_layout-sidenav.html.erb
_application.html.erb
Main layout
...
...
bin
config
environments
initializers
assets.rb
Asset pipeline config
...
locales
autoprefixer.yml
Autoprefixer config
...
db
lib
log
public
test
tmp
vendor
assets
Appwork's sources
fonts
Iconic fonts
fontawesome.css.erb
ionicons.css.erb
...
javascripts
Javascripts
bootstrap.js
dropdown-hover.js
...
libs
Third-party libraries
animate-css
autosize
block-ui
...
stylesheets
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
...
package.json
...

Third-party plugins

The starter project by default includes all third-party plugins (see config/initializers/assets.rb file).
Optionally you can remove unwanted plugins to reduce output assets size and compile time:

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

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

  1. Remove plyr dependency in the package.json file.
  2. Remove the vendor/assets/libs/plyr directory.
  3. Remove @import "../../libs/plyr/mixins"; and @include plyr-theme($background, $color); lines in the vendor/assets/stylesheets/_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. Download and install Rails Installer with Ruby v2.3 and above from http://railsinstaller.org/en.
  7. Logout from the system and login again.
  8. Open cmd.exe and go to the rails-starter directory.
  9. Run command bundle install.
  10. Run command yarn install.
  11. Now you can run the server: bundle exec rails s.
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 a terminal.
  7. Run command sudo apt-get install zlib1g-dev build-essential libssl-dev libreadline-dev libyaml-dev libsqlite3-dev sqlite3 libxml2-dev libxslt1-dev libcurl4-openssl-dev python-software-properties libffi-dev.
  8. Install Ruby: sudo apt-add-repository ppa:brightbox/ruby-ng; sudo apt-get update; sudo apt-get install ruby2.4 ruby2.4-dev.
  9. Run command sudo gem install bundler.
  10. Go to the rails-starter directory.
  11. Run command bundle install.
  12. Run command yarn install.
  13. Now you can run the server: bundle exec rails s.
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 a terminal.
  7. Check ruby version (minimum required version is 2.3.3) by executing ruby -v command in the terminal. Update ruby if required.
  8. Run command sudo gem install bundler.
  9. Go to the rails-starter directory.
  10. Run command bundle install.
  11. Run command yarn install.
  12. Now you can run the server: bundle exec rails s.

Page structure

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

Main layout

app/views/layouts/application.html.erb
<!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">

  <%= csrf_meta_tags %>
  <%= csp_meta_tag %>

  <title><%= @title ? @title + " - " : "" %>Rails Starter</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 -->
  <!-- <%= stylesheet_link_tag 'fontawesome.css', media: 'all', 'data-turbolinks-track': 'reload' %> -->
  <%= stylesheet_link_tag 'ionicons.css', media: 'all', 'data-turbolinks-track': 'reload' %>
  <!-- <%= stylesheet_link_tag 'linearicons.css', media: 'all', 'data-turbolinks-track': 'reload' %> -->
  <!-- <%= stylesheet_link_tag 'open-iconic.css', media: 'all', 'data-turbolinks-track': 'reload' %> -->
  <!-- <%= stylesheet_link_tag 'pe-icon-7-stroke.css', media: 'all', 'data-turbolinks-track': 'reload' %> -->

  <!-- Core stylesheets -->
  <%= stylesheet_link_tag 'bootstrap.css', media: 'all', 'data-turbolinks-track': 'reload' %>
  <%= stylesheet_link_tag 'appwork.css', media: 'all', 'data-turbolinks-track': 'reload' %>
  <%= stylesheet_link_tag 'theme-corporate.css', media: 'all', 'data-turbolinks-track': 'reload' %>
  <%= stylesheet_link_tag 'colors.css', media: 'all', 'data-turbolinks-track': 'reload' %>
  <%= stylesheet_link_tag 'uikit.css', media: 'all', 'data-turbolinks-track': 'reload' %>
  <%= stylesheet_link_tag 'application', media: 'all', 'data-turbolinks-track': 'reload' %>

  <!-- Layout helpers -->
  <%= javascript_include_tag 'layout-helpers.js', 'data-turbolinks-track': 'reload' %>

  <!-- jQuery -->
  <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.2.1/jquery.min.js"></script>

  <!-- Libs -->

  <!-- `perfect-scrollbar` library required by SideNav plugin -->
  <%= stylesheet_link_tag 'perfect-scrollbar/perfect-scrollbar.css', media: 'all', 'data-turbolinks-track': 'reload' %>
  <%= javascript_include_tag 'perfect-scrollbar/perfect-scrollbar.js', 'data-turbolinks-track': 'reload' %>

  <!-- Core scripts -->
  <%= javascript_include_tag 'popper/popper.js', 'data-turbolinks-track': 'reload' %>
  <%= javascript_include_tag 'bootstrap.js', 'data-turbolinks-track': 'reload' %>
  <%= javascript_include_tag 'sidenav.js', 'data-turbolinks-track': 'reload' %>
  <%= javascript_include_tag 'application', 'data-turbolinks-track': 'reload' %>

  <%= yield :head %>
</head>
<body>

  <%= content_for?(:content) ? yield(:content) : yield %>

</body>
</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">

  <%= csrf_meta_tags %>
  <%= csp_meta_tag %>
  <meta name="turbolinks-cache-control" content="no-preview">

  <title><%= @title ? @title + " - " : "" %>Rails Starter</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 -->
  <!-- <%= stylesheet_link_tag 'fontawesome.css', media: 'all', 'data-turbolinks-track': 'reload' %> -->
  <%= stylesheet_link_tag 'ionicons.css', media: 'all', 'data-turbolinks-track': 'reload' %>
  <!-- <%= stylesheet_link_tag 'linearicons.css', media: 'all', 'data-turbolinks-track': 'reload' %> -->
  <!-- <%= stylesheet_link_tag 'open-iconic.css', media: 'all', 'data-turbolinks-track': 'reload' %> -->
  <!-- <%= stylesheet_link_tag 'pe-icon-7-stroke.css', media: 'all', 'data-turbolinks-track': 'reload' %> -->

  <!-- Core stylesheets -->
  <%= stylesheet_link_tag 'bootstrap.css', media: 'all', class: 'theme-settings-bootstrap-css' %>
  <%= stylesheet_link_tag 'appwork.css', media: 'all', class: 'theme-settings-appwork-css' %>
  <%= stylesheet_link_tag 'theme-corporate.css', media: 'all', class: 'theme-settings-theme-css' %>
  <%= stylesheet_link_tag 'colors.css', media: 'all', class: 'theme-settings-colors-css' %>
  <%= stylesheet_link_tag 'uikit.css', media: 'all', 'data-turbolinks-track': 'reload' %>
  <%= stylesheet_link_tag 'application', media: 'all', 'data-turbolinks-track': 'reload' %>

  <!-- Layout helpers -->
  <%= javascript_include_tag 'layout-helpers.js', 'data-turbolinks-track': 'reload' %>

  <!-- Theme settings -->
  <%= javascript_include_tag 'theme-settings.js', 'data-turbolinks-track': 'reload' %>
  <script>
    // Use settings panel generator to configure the plugin
    window.themeSettings = new ThemeSettings({
      cssPath: '',
      themesPath: '',
      pathResolver: function(path) {
        var resolvedPaths = {
          // Core stylesheets
        <%- ['bootstrap', 'appwork', 'colors'].each do |name| %>
          '<%= name %>.css': '<%= asset_path "#{name}.css" %>',
          '<%= name %>-material.css': '<%= asset_path "#{name}-material.css" %>',
        <% end %>

          // UI Kit
          'uikit.css': '<%= asset_path "uikit.css" %>',

          // Themes
        <%- ['air', 'corporate', 'cotton', 'gradient', 'paper', 'shadow', 'soft', 'sunrise', 'twitlight', 'vibrant'].each do |name| %>
          'theme-<%= name %>.css': '<%= asset_path "theme-#{name}.css" %>',
          'theme-<%= name %>-material.css': '<%= asset_path "theme-#{name}-material.css" %>',
        <% end %>
        };

        return resolvedPaths[path] || path;
      }
    });
  </script>

  <!-- jQuery -->
  <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.2.1/jquery.min.js"></script>

  <!-- Libs -->

  <!-- `perfect-scrollbar` library required by SideNav plugin -->
  <%= stylesheet_link_tag 'perfect-scrollbar/perfect-scrollbar.css', media: 'all', 'data-turbolinks-track': 'reload' %>
  <%= javascript_include_tag 'perfect-scrollbar/perfect-scrollbar.js', 'data-turbolinks-track': 'reload' %>

  <!-- Core scripts -->
  <%= javascript_include_tag 'popper/popper.js', 'data-turbolinks-track': 'reload' %>
  <%= javascript_include_tag 'bootstrap.js', 'data-turbolinks-track': 'reload' %>
  <%= javascript_include_tag 'sidenav.js', 'data-turbolinks-track': 'reload' %>
  <%= javascript_include_tag 'application', 'data-turbolinks-track': 'reload' %>

  <%= yield :head %>
</head>
<body>

  <%= content_for?(:content) ? yield(:content) : yield %>

</body>
</html>

Layouts

There are several ways you can set the layout:

  1. Layout for the entire app - define layout declaration in the ApplicationController.
  2. Layout for the specified controller - define layout declaration in the SomeController.
  3. Layout for the specified action - render view with the layout option.

You can find navbar, sidenav and footer templates in the app/views/layouts/partials directory. 

app/controllers/some_controller.rb
class SomeController < ApplicationController
  layout 'main/layout-1'

  def index
    render layout: 'main/layout-1'
  end
end
app/controllers/some_controller.rb
class SomeController < ApplicationController
  layout 'main/layout-1-flex'

  def index
    render layout: 'main/layout-1-flex'
  end
end
app/controllers/some_controller.rb
class SomeController < ApplicationController
  layout 'main/layout-2'

  def index
    render layout: 'main/layout-2'
  end
end
app/controllers/some_controller.rb
class SomeController < ApplicationController
  layout 'main/layout-2-flex'

  def index
    render layout: 'main/layout-2-flex'
  end
end
app/controllers/some_controller.rb
class SomeController < ApplicationController
  layout 'main/layout-without-navbar'

  def index
    render layout: 'main/layout-without-navbar'
  end
end
app/controllers/some_controller.rb
class SomeController < ApplicationController
  layout 'main/layout-without-navbar-flex'

  def index
    render layout: 'main/layout-without-navbar-flex'
  end
end
app/controllers/some_controller.rb
class SomeController < ApplicationController
  layout 'main/layout-without-sidenav'

  def index
    render layout: 'main/layout-without-sidenav'
  end
end
app/controllers/some_controller.rb
class SomeController < ApplicationController
  layout 'main/layout-horizontal-sidenav'

  def index
    render layout: 'main/layout-horizontal-sidenav'
  end
end
app/controllers/some_controller.rb
class SomeController < ApplicationController
  layout 'main/layout-blank'

  def index
    render layout: 'main/layout-blank'
  end
end

Precompile stylesheets

To use settings panel, you need to add Appwork's stylesheets to the precompilation list (use the generator to see the example):

config/initializers/assets.rb
...

# Precompile core stylesheets
Rails.application.config.assets.precompile += [
  # Core stylesheets
  'stylesheets/bootstrap.css',
  'stylesheets/bootstrap-material.css',
  'stylesheets/appwork.css',
  'stylesheets/appwork-material.css',
  'stylesheets/colors.css',
  'stylesheets/colors-material.css',
  'stylesheets/uikit.css',

  # Themes
  'stylesheets/theme-air.css',
  'stylesheets/theme-air-material.css',
  ...
]

...

Theming

To enable a theme you need to:

  1. Add theme file to the precompilation list in the config/initializers/assets.rb.

    config/initializers/assets.rb
    ...

# Precompile core stylesheets
Rails.application.config.assets.precompile += [
  ...
  "stylesheets/theme-air.css",
  ...
]

...

  2. Include theme stylesheet.

    app/views/layouts/application.html.erb
    <%= stylesheet_link_tag 'theme-air.css', media: 'all', 'data-turbolinks-track': 'reload' %>

To enable a theme just include the required theme stylesheet. 

app/views/layouts/application.html.erb
<%= stylesheet_link_tag 'theme-air.css', media: 'all', 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.

    app/views/layouts/application.html.erb
    <html class="material-style">

  2. Add -material suffix to bootstrap.css, appwork.css, theme-*.css and colors.css paths in the config/initializers/assets.rb.

    config/initializers/assets.rb
    ...

# Precompile core stylesheets
Rails.application.config.assets.precompile += [
  "stylesheets/bootstrap-material.css",
  "stylesheets/appwork-material.css",
  "stylesheets/theme-corporate-material.css",
  "stylesheets/colors-material.css",
  ...
]

...

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

    app/views/layouts/application.html.erb
    <%= stylesheet_link_tag 'bootstrap-material.css', media: 'all', 'data-turbolinks-track': 'reload' %>
<%= stylesheet_link_tag 'appwork-material.css', media: 'all', 'data-turbolinks-track': 'reload' %>
<%= stylesheet_link_tag 'theme-corporate-material.css', media: 'all', 'data-turbolinks-track': 'reload' %>
<%= stylesheet_link_tag 'colors-material.css', media: 'all', 'data-turbolinks-track': 'reload' %>
    <%= stylesheet_link_tag 'bootstrap-material.css', media: 'all', class: 'theme-settings-bootstrap-css' %>
<%= stylesheet_link_tag 'appwork-material.css', media: 'all', class: 'theme-settings-appwork-css' %>
<%= stylesheet_link_tag 'theme-corporate-material.css', media: 'all', class: 'theme-settings-theme-css' %>
<%= stylesheet_link_tag 'colors-material.css', media: 'all', 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. 

    app/views/layouts/application.html.erb
    <%= javascript_include_tag 'material-ripple.js', 'data-turbolinks-track': 'reload' %>
<script>
  window.attachMaterialRippleOnLoad();
</script>

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

    app/views/layouts/application.html.erb
    <%= javascript_include_tag 'material-ripple.js', 'data-turbolinks-track': 'reload' %>

RTL support

To enable RTL direction support:

  1. Open config/initializers/assets.rb file and edit paths to load Appwork's stylesheets from the stylesheets/rtl/ directory instead of stylesheets/. 

    config/initializers/assets.rb
    ...

# Precompile core stylesheets
Rails.application.config.assets.precompile += [
  "stylesheets/rtl/bootstrap.css",
  "stylesheets/rtl/appwork.css",
  "stylesheets/rtl/theme-corporate.css",
  "stylesheets/rtl/colors.css",
  "stylesheets/rtl/uikit.css"
]

...
    ...

# Precompile core stylesheets
Rails.application.config.assets.precompile += [
  # Core stylesheets
  'stylesheets/rtl/bootstrap.css',
  'stylesheets/rtl/bootstrap-material.css',
  'stylesheets/rtl/appwork.css',
  'stylesheets/rtl/appwork-material.css',
  ...
]

...

  2. Import Appwork's stylesheets from the rtl/ path.

    app/views/layouts/application.html.erb
    <%= stylesheet_link_tag 'rtl/bootstrap.css', media: 'all', 'data-turbolinks-track': 'reload' %>
<%= stylesheet_link_tag 'rtl/appwork.css', media: 'all', 'data-turbolinks-track': 'reload' %>
<%= stylesheet_link_tag 'rtl/theme-corporate.css', media: 'all', 'data-turbolinks-track': 'reload' %>
<%= stylesheet_link_tag 'rtl/colors.css', media: 'all', 'data-turbolinks-track': 'reload' %>
<%= stylesheet_link_tag 'rtl/uikit.css', media: 'all', 'data-turbolinks-track': 'reload' %>
    <%= stylesheet_link_tag 'rtl/bootstrap.css', media: 'all', class: 'theme-settings-bootstrap-css' %>
<%= stylesheet_link_tag 'rtl/appwork.css', media: 'all', class: 'theme-settings-appwork-css' %>
<%= stylesheet_link_tag 'rtl/theme-corporate.css', media: 'all', class: 'theme-settings-theme-css' %>
<%= stylesheet_link_tag 'rtl/colors.css', media: 'all', class: 'theme-settings-colors-css' %>
<%= stylesheet_link_tag 'rtl/uikit.css', media: 'all', 'data-turbolinks-track': 'reload' %>

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

app/views/layouts/application.html.erb
<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. 
app/views/layouts/application.html.erb
<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.

    app/views/layouts/application.html.erb
    <%= javascript_include_tag 'pace.js', 'data-turbolinks-track': 'reload' %>

  2. Append .page-loader element to the <body>.

    app/views/layouts/application.html.erb
    <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 rails-starter directory.

Open in new tab