Docs v1.6.0  /  Rails + Turbolinks HTML5 Angular Vue.js React Laravel Laravel + Vue.js Rails ASP.NET Core ASP.NET Core MVC ASP.NET MVC ASP.NET MVC + Webpack
OTHER
Settings panel Layout helpers

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

rails-turbolinks-starter directory structure

rails-turbolinks-starter
app
assets
channels
controllers
helpers
javascript
Javascript scripts
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
webpack
Webpack config
appwork.js
Appwork's build config
...
locales
autoprefixer.yml
Autoprefixer config
webpacker.yml
Autoprefixer config
...
db
lib
log
public
storage
test
tmp
vendor
assets
Appwork's sources
fonts
Iconic fonts
fontawesome.css
ionicons.css
...
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
appwork-dark.scss
...
babel.config.js
package.json
postcss.config.js
...

Third-party plugins

The starter project by default includes all third-party plugins.
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 latest Node.js LTS: https://nodejs.org/en/.
  2. Download and install Git: https://git-scm.com/downloads.
  3. Logout from the system and login again.
  4. Install Yarn globally: npm i -g yarn
  5. Launch cmd.exe as an administrator and run command npm install --add-python-to-path='true' --global --production windows-build-tools.

  6. Now you need to install Ruby and required gems. Don't use RailsInstaller because it uses outdated Ruby version that isn't supported by Rails 6.

    1. Download and install latest Ruby+DevKit package compatible with your system architecture: https://rubyinstaller.org/downloads/.
    2. After installing, select [3] (MSYS2 and MINGW) in the command prompt window.
    3. Logout from the system and login again.
    4. Download and install MSYS2 package compatible with your system architecture: https://www.msys2.org/.
    5. Load a new MSYS2 console and type pacman -Sy pacman.
    6. Install C-dependent gems: https://github.com/oneclick/rubyinstaller2#install-gems-with-c-extensions-and-additional-library-dependencies
  7. Install Bundler: gem install bundler
  8. Install Rails: gem install rails
  9. Go to the rails-turbolinks-starter directory and run command bundle install.
  10. Run command npm install.
  11. Now you can run the server: bundle exec rails s.
Ubuntu
  1. Update system: sudo apt-get update && sudo apt-get upgrade.
  2. Install curl: sudo apt-get install curl.
  3. Install latest Node.js LTS and build tools: https://nodejs.org/en/download/package-manager/#debian-and-ubuntu-based-linux-distributions-enterprise-linux-fedora-and-snap-packages.
  4. Install Git: https://git-scm.com/download/linux.
  5. Install Yarn globally: npm i -g yarn
  6. 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 software-properties-common libffi-dev.
  7. Install Ruby: sudo apt-add-repository ppa:brightbox/ruby-ng; sudo apt-get update; sudo apt-get install ruby2.6 ruby2.6-dev.
  8. Install Bundler: gem install bundler
  9. Install Rails: gem install rails
  10. Go to the rails-turbolinks-starter directory and run command bundle install.
  11. Run command npm install.
  12. 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. Download and install latest Node.js LTS: https://nodejs.org/en/.
  3. Download and install Git: https://git-scm.com/downloads.
  4. Install Yarn globally: npm i -g yarn
  5. Check Ruby version (minimum required version is 2.5) by executing ruby -v command in the terminal. Update ruby if required.
  6. Install Bundler: gem install bundler
  7. Install Rails: gem install rails
  8. Go to the rails-turbolinks-starter directory and run command bundle install.
  9. Run command npm install.
  10. 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="light-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 + Turbolinks 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_pack_tag 'vendor/fonts/fontawesome', media: 'all', 'data-turbolinks-track': 'reload' %> -->
  <%= stylesheet_pack_tag 'vendor/fonts/ionicons', media: 'all', 'data-turbolinks-track': 'reload' %>
  <!-- <%= stylesheet_pack_tag 'vendor/fonts/linearicons', media: 'all', 'data-turbolinks-track': 'reload' %> -->
  <!-- <%= stylesheet_pack_tag 'vendor/fonts/open-iconic', media: 'all', 'data-turbolinks-track': 'reload' %> -->
  <!-- <%= stylesheet_pack_tag 'vendor/fonts/pe-icon-7-stroke', media: 'all', 'data-turbolinks-track': 'reload' %> -->

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

  <!-- Load polyfills -->
  <%= javascript_pack_tag 'vendor/polyfills', 'data-turbolinks-track': 'reload' %>
  <script>document['documentMode']===10&&document.write('<script src="https://polyfill.io/v3/polyfill.min.js?features=Intl.~locale.en"><\/script>')</script>

  <!-- Layout helpers -->
  <%= javascript_pack_tag 'vendor/layout-helpers', '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_pack_tag 'vendor/libs/perfect-scrollbar/perfect-scrollbar', media: 'all', 'data-turbolinks-track': 'reload' %>
  <%= javascript_pack_tag 'vendor/libs/perfect-scrollbar/perfect-scrollbar', 'data-turbolinks-track': 'reload' %>

  <!-- Core scripts -->
  <%= javascript_pack_tag 'vendor/libs/popper/popper', 'data-turbolinks-track': 'reload' %>
  <%= javascript_pack_tag 'vendor/bootstrap', 'data-turbolinks-track': 'reload' %>
  <%= javascript_pack_tag 'vendor/sidenav', 'data-turbolinks-track': 'reload' %>
  <%= javascript_pack_tag 'application', 'data-turbolinks-track': 'reload' %>

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

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

</body>
</html>
<!DOCTYPE html>

<html lang="en" class="light-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 + Turbolinks 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_pack_tag 'vendor/fonts/fontawesome', media: 'all', 'data-turbolinks-track': 'reload' %> -->
  <%= stylesheet_pack_tag 'vendor/fonts/ionicons', media: 'all', 'data-turbolinks-track': 'reload' %>
  <!-- <%= stylesheet_pack_tag 'vendor/fonts/linearicons', media: 'all', 'data-turbolinks-track': 'reload' %> -->
  <!-- <%= stylesheet_pack_tag 'vendor/fonts/open-iconic', media: 'all', 'data-turbolinks-track': 'reload' %> -->
  <!-- <%= stylesheet_pack_tag 'vendor/fonts/pe-icon-7-stroke', media: 'all', 'data-turbolinks-track': 'reload' %> -->

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

  <!-- Load polyfills -->
  <%= javascript_pack_tag 'vendor/polyfills', 'data-turbolinks-track': 'reload' %>
  <script>document['documentMode']===10&&document.write('<script src="https://polyfill.io/v3/polyfill.min.js?features=Intl.~locale.en"><\/script>')</script>

  <!-- Layout helpers -->
  <%= javascript_pack_tag 'vendor/layout-helpers', 'data-turbolinks-track': 'reload' %>

  <!-- Theme settings -->
  <%= javascript_pack_tag 'vendor/theme-settings', 'data-turbolinks-track': 'reload' %>
  <%= stylesheet_pack_tag 'vendor/theme-settings', media: 'all', '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_pack_path "vendor/#{name}.css" %>',
            '<%= name %>-material.css': '<%= asset_pack_path "vendor/#{name}-material.css" %>',
            '<%= name %>-dark.css': '<%= asset_pack_path "vendor/#{name}-dark.css" %>',
          <% end %>

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

          // Themes
          <%- ['air', 'corporate', 'cotton', 'gradient', 'paper', 'shadow', 'soft', 'sunrise', 'twitlight', 'vibrant'].each do |name| %>
            'theme-<%= name %>.css': '<%= asset_pack_path "vendor/theme-#{name}.css" %>',
            'theme-<%= name %>-material.css': '<%= asset_pack_path "vendor/theme-#{name}-material.css" %>',
            'theme-<%= name %>-dark.css': '<%= asset_pack_path "vendor/theme-#{name}-dark.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_pack_tag 'vendor/libs/perfect-scrollbar/perfect-scrollbar', media: 'all', 'data-turbolinks-track': 'reload' %>
  <%= javascript_pack_tag 'vendor/libs/perfect-scrollbar/perfect-scrollbar', 'data-turbolinks-track': 'reload' %>

  <!-- Core scripts -->
  <%= javascript_pack_tag 'vendor/libs/popper/popper', 'data-turbolinks-track': 'reload' %>
  <%= javascript_pack_tag 'vendor/bootstrap', 'data-turbolinks-track': 'reload' %>
  <%= javascript_pack_tag 'vendor/sidenav', 'data-turbolinks-track': 'reload' %>
  <%= javascript_pack_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 in the ApplicationController.
  2. Layout for the specified controller - define layout in SomeController.
  3. Layout for the specified action - render view with 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

Theming

To enable a theme, include theme stylesheet in your main layout.

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

To enable a theme just include the required theme stylesheet. 

app/views/layouts/application.html.erb
<%= stylesheet_pack_tag 'vendor/theme-air', media: 'all', class: 'theme-settings-theme-css' %>

Material styling

To enable material styling you need to:

  1. Set $enable-material-style variable to true.

    vendor/assets/stylesheets/_custom-variables/_features.scss
    ...
$enable-material-style: true;
...

  2. Set material-style class on the <html> element instead of light-style.

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

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

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

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

    app/views/layouts/application.html.erb
    <%= javascript_pack_tag 'vendor/material-ripple', 'data-turbolinks-track': 'reload' %>
<%= stylesheet_pack_tag 'vendor/material-ripple', media: 'all', '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_pack_tag 'vendor/material-ripple', 'data-turbolinks-track': 'reload' %>
<%= stylesheet_pack_tag 'vendor/material-ripple', media: 'all', 'data-turbolinks-track': 'reload' %>

Dark styling

To enable dark styling you need to:

  1. Set $enable-dark-style variable to true.

    vendor/assets/stylesheets/_custom-variables/_features.scss
    ...
$enable-dark-style: true;
...

  2. Set dark-style class on the <html> element instead of light-style.

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

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

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

RTL support

To enable RTL direction support:

  1. Set $enable-rtl-support variable to true.

    vendor/assets/stylesheets/_custom-variables/_features.scss
    $enable-rtl-support: true;
...

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

    app/views/layouts/application.html.erb
    <%= stylesheet_pack_tag 'vendor/rtl/bootstrap', media: 'all', 'data-turbolinks-track': 'reload' %>
<%= stylesheet_pack_tag 'vendor/rtl/appwork', media: 'all', 'data-turbolinks-track': 'reload' %>
<%= stylesheet_pack_tag 'vendor/rtl/theme-corporate', media: 'all', 'data-turbolinks-track': 'reload' %>
<%= stylesheet_pack_tag 'vendor/rtl/colors', media: 'all', 'data-turbolinks-track': 'reload' %>
<%= stylesheet_pack_tag 'vendor/rtl/uikit', media: 'all', 'data-turbolinks-track': 'reload' %>
    <%= stylesheet_pack_tag 'vendor/rtl/bootstrap', media: 'all', class: 'theme-settings-bootstrap-css' %>
<%= stylesheet_pack_tag 'vendor/rtl/appwork', media: 'all', class: 'theme-settings-appwork-css' %>
<%= stylesheet_pack_tag 'vendor/rtl/theme-corporate', media: 'all', class: 'theme-settings-theme-css' %>
<%= stylesheet_pack_tag 'vendor/rtl/colors', media: 'all', class: 'theme-settings-colors-css' %>
<%= stylesheet_pack_tag 'vendor/rtl/uikit', 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_pack_tag 'vendor/pace', '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-turbolinks-starter directory.

Open in new tab

Migration guide

Do not forget to commit changes or clone the project before performing migration steps.

Official Ruby on Rails changelogs: https://weblog.rubyonrails.org/releases/.

  1. Check your Ruby version ruby -v. Upgrade it if the version is less than 2.5.0.

  2. Upgrade Node.js to the latest LTS release (https://nodejs.org/en/)

  3. Remove the next files and directories:

    vendor/assets/libs/vegas/

  4. Copy new files and directories:

    config/initializers/permissions_policy.rb

  5. Since some extensions were removed from the bootstrap-table package, remove vendor/assets/libs/bootstrap-table/ directory and copy new appwork-v1_6_0/rails-turbolinks-starter/vendor/assets/libs/bootstrap-table/

  6. Copy with replace all SCSS files within vendor/assets/stylesheets/ and vendor/assets/stylesheets/rtl/ directories:

    vendor/assets/stylesheets/*.scss
vendor/assets/stylesheets/rtl/*.scss

  7. Copy with replace changed files and directories:

    .gitattributes
.gitignore
config.ru
bin/
vendor/assets/fonts/
vendor/assets/stylesheets/_appwork/
vendor/assets/stylesheets/_uikit/
vendor/assets/libs/blueimp-gallery/
vendor/assets/libs/bootstrap-slider/
vendor/assets/libs/dropzone/
vendor/assets/libs/fullcalendar/
vendor/assets/libs/nouislider/
vendor/assets/libs/minicolors/
vendor/assets/libs/photoswipe/
vendor/assets/libs/plyr/
vendor/assets/libs/select2/
vendor/assets/libs/smartwizard/
vendor/assets/libs/sortablejs/
vendor/assets/libs/swiper/
vendor/assets/libs/timepicker/
vendor/assets/libs/typeahead-js/

  8. Update:

    Gemfile. Diff

    package.json. Diff

    app/javascript/packs/application.js. Diff

    config/application.rb. Diff

    config/puma.rb. Diff

    config/webpacker.yml. Diff

    config/environments/development.rb. Diff

    config/environments/production.rb. Diff

    config/environments/test.rb. Diff

    config/initializers/backtrace_silencers.rb. Diff

    config/initializers/filter_parameter_logging.rb. Diff

  9. Set your Ruby version in Gemfile and .ruby-version

  10. Remove Gemfile.lock

  11. Remove node_modules directory and package-lock.json. Then execute npm install

  12. Execute bundle install

Changes in third-party components:

  • vegas plugin was excluded from the package.

  • fullcalendar changed its API and configuration object:

    Before
    var eventList = [{
  ...
  className: 'fc-event-warning'
}, {
  ...
  rendering: 'background'
}];

new Calendar($('#id')[0], {
  ...
  defaultDate: ...,
  eventLimit: ...,
  defaultView: '...',
  dir: 'rtl',
  header: {
    ...
    left: '...',
    right: '...'
  },
  views: {
    dayGrid: {
      eventLimit: ...
    }
  },
});
    After
    var eventList = [{
  ...
  classNames: 'fc-event-warning'
}, {
  ...
  display: 'background'
}];

new Calendar($('#id')[0], {
  ...
  initialDate: ...,
  dayMaxEventRows: ...,
  initialView: '...',
  direction: 'rtl',
  headerToolbar: {
    ...
    start: '...',
    end: '...'
  },
  views: {
    dayGrid: {
      dayMaxEventRows: ...
    }
  },
});

    For more info see https://fullcalendar.io/docs/upgrading-from-v4

  • dropzone configuration is changed.

    Before
    $('#id').dropzone();
    After
    var previewTemplate =
  '<div class="dz-preview dz-file-preview">' +
  '  <div class="dz-details">' +
  '    <div class="dz-thumbnail">' +
  '      <img data-dz-thumbnail>' +
  '      <span class="dz-nopreview">No preview</span>' +
  '      <div class="dz-success-mark"></div>' +
  '      <div class="dz-error-mark"></div>' +
  '      <div class="dz-error-message"><span data-dz-errormessage></span></div>' +
  '      <div class="progress"><div class="progress-bar progress-bar-primary" role="progressbar" aria-valuemin="0" aria-valuemax="100" data-dz-uploadprogress></div></div>' +
  '    </div>' +
  '    <div class="dz-filename" data-dz-name></div>' +
  '    <div class="dz-size" data-dz-size></div>' +
  '  </div>' +
  '</div>';
            
$('#id').dropzone({
  previewTemplate: previewTemplate
});

  • smartwizard markup and API are changed.

    Before
    <ul>
  <li><a href="#" class="mb-3">...</a></li>
  ...
</ul>

<div class="mb-3">
  <div id="smartwizard-1-step-1" class="card animated fadeIn">
    ...
  </div>
</div>
    After
    <ul class="nav">
  <li><a href="#" class="nav-link mb-3">...</a></li>
  ...
</ul>

<div class="tab-content mb-3">
  <div id="#" class="tab-pane card" role="tabpanel">
    ...
  </div>
</div>
    Before
    $el.smartWizard({
  useURLhash: false,
  showStepURLhash: false,
  ...
})
.on('leaveStep', function(e, anchorObject, stepNumber, stepDirection) {
  if (stepDirection === 'forward'){ return $el.valid(); }
  return true;
})
.on('showStep', function(e, anchorObject, stepNumber, stepDirection) {
  var $btn = $el.find('.btn-finish');

  if (stepNumber === 3) {
    $btn.removeClass('hidden');
  } else {
    $btn.addClass('hidden');
  }
});
    After
    $el.smartWizard({
  enableURLhash: false,
  ...
})
.on('leaveStep', function(e, anchorObject, currentStepIndex, nextStepIndex, stepDirection) {
  var $finishBtn = $el.find('.btn-finish');

  if (stepDirection === 'forward'){
    var isValid = $el.valid();

    if (!isValid) {
      anchorObject.addClass('danger');
    } else {
      anchorObject.removeClass('danger');

      if (nextStepIndex === 3) {
        $finishBtn.removeClass('d-none');
      }
    }

    return isValid;
  } else {
    $finishBtn.addClass('d-none');
  }

  return true;
})
.find('> .toolbar .btn:not(.btn-primary)').addClass('btn-secondary');

    For more info see http://techlaboratory.net/jquery-smartwizard

  • Copy with replace the next files and directories:

    vendor/assets/stylesheets/_appwork/_functions.scss
vendor/assets/libs/bootstrap-datepicker/
vendor/assets/libs/bootstrap-daterangepicker/
vendor/assets/libs/bootstrap-material-datetimepicker/
vendor/assets/libs/bootstrap-select/
vendor/assets/libs/flatpickr/
vendor/assets/libs/growl/
vendor/assets/libs/plyr/
vendor/assets/libs/select2/
vendor/assets/libs/sweetalert2/
vendor/assets/libs/timepicker/
vendor/assets/libs/typeahead-js/

  • Copy with replace the next file:

    vendor/assets/libs/flatpickr/flatpickr.scss

  1. Check the Ruby version ruby -v. Upgrade it if the version is less than 2.5.0.

  2. Upgrade Node.js to the latest LTS release (https://nodejs.org/en/)

    Note: Yarn package manager is not reqired anymore.

  3. Remove the next files and directories:

    vendor/assets/stylesheets/migrate/

  4. Copy new files and directories:

    vendor/assets/stylesheets/_custom-variables/_appwork-dark.scss
vendor/assets/stylesheets/_custom-variables/_features.scss

  5. Since some extensions were removed from the bootstrap-table package, remove vendor/assets/libs/bootstrap-table/ directory and copy new appwork-v1_5_0/rails-turbolinks-starter/vendor/assets/libs/bootstrap-table/

  6. Copy with replace all SCSS files within vendor/assets/stylesheets/ and vendor/assets/stylesheets/rtl/ directories:

    vendor/assets/stylesheets/*.scss
vendor/assets/stylesheets/rtl/*.scss

  7. Copy with replace changed files and directories:

    bin/webpack
bin/webpack-dev-server
vendor/assets/fonts/fontawesome/
vendor/assets/fonts/fontawesome.css
vendor/assets/javascripts/bootstrap.js
vendor/assets/javascripts/layout-helpers.js
vendor/assets/javascripts/polyfills.js
vendor/assets/javascripts/sidenav.js
vendor/assets/javascripts/theme-settings.js
vendor/assets/javascripts/_theme-settings/
vendor/assets/stylesheets/_appwork/
vendor/assets/stylesheets/_theme/
vendor/assets/stylesheets/_uikit/
vendor/assets/stylesheets/pages/
vendor/assets/libs/autosize/
vendor/assets/libs/block-ui/
vendor/assets/libs/blueimp-gallery/
vendor/assets/libs/bootbox/
vendor/assets/libs/bootstrap-datepicker/
vendor/assets/libs/bootstrap-daterangepicker/
vendor/assets/libs/bootstrap-duallistbox/
vendor/assets/libs/bootstrap-markdown/
vendor/assets/libs/bootstrap-material-datetimepicker/
vendor/assets/libs/bootstrap-maxlength/
vendor/assets/libs/bootstrap-menu/
vendor/assets/libs/bootstrap-select/
vendor/assets/libs/bootstrap-slider/
vendor/assets/libs/bootstrap-sortable/
vendor/assets/libs/bootstrap-tagsinput/
vendor/assets/libs/c3/
vendor/assets/libs/chartist/
vendor/assets/libs/chartjs/
vendor/assets/libs/clipboard/
vendor/assets/libs/cropper/
vendor/assets/libs/d3/
vendor/assets/libs/datatables/
vendor/assets/libs/dragula/
vendor/assets/libs/dropzone/
vendor/assets/libs/eve/
vendor/assets/libs/flatpickr/
vendor/assets/libs/flot/
vendor/assets/libs/flow-js/
vendor/assets/libs/fullcalendar/
vendor/assets/libs/gmaps/
vendor/assets/libs/growl/
vendor/assets/libs/jstree/
vendor/assets/libs/knob/
vendor/assets/libs/ladda/
vendor/assets/libs/mapael/
vendor/assets/libs/markdown/
vendor/assets/libs/masonry/
vendor/assets/libs/minicolors/
vendor/assets/libs/moment/
vendor/assets/libs/morris/
vendor/assets/libs/nestable/
vendor/assets/libs/nouislider/
vendor/assets/libs/numeral/
vendor/assets/libs/perfect-scrollbar/
vendor/assets/libs/photoswipe/
vendor/assets/libs/plyr/
vendor/assets/libs/popper/
vendor/assets/libs/pwstrength-bootstrap/
vendor/assets/libs/quill/
vendor/assets/libs/raphael/
vendor/assets/libs/select2/
vendor/assets/libs/shepherd/
vendor/assets/libs/smartwizard/
vendor/assets/libs/sortablejs/
vendor/assets/libs/sparkline/
vendor/assets/libs/spin/
vendor/assets/libs/spinkit/
vendor/assets/libs/sweetalert2/
vendor/assets/libs/swiper/
vendor/assets/libs/tableexport/
vendor/assets/libs/timepicker/
vendor/assets/libs/toastr/
vendor/assets/libs/typeahead-js/
vendor/assets/libs/validate/
vendor/assets/libs/vanilla-text-mask/
vendor/assets/libs/vegas/

  8. Update:

    babel.config.js. Diff

    Gemfile. Diff

    package.json. Diff

    vendor/assets/stylesheets/_custom-variables/_libs.scss. Diff

    vendor/assets/stylesheets/_custom-variables/_pages.scss. Diff

    vendor/assets/stylesheets/_custom-variables/_uikit.scss. Diff

  9. Edit variables in the vendor/assets/stylesheets/_custom-variables/_features.scss file according your setup.

    Variable Feature
    $enable-rtl-support Set to true to enable RTL mode support, otherwise set to false.
    $enable-light-style Set to true to enable light (previously default) style support, otherwise set to false.
    $enable-material-style Set to true to enable material style support, otherwise set to false.
    $enable-dark-style Set to true to enable dark style support, otherwise set to false.

  10. Remove Gemfile.lock

  11. Remove node_modules directory and then execute npm install

  12. Execute bundle install

  • theme-default class is renamed to theme-light.

    [Before] app/views/layouts/application.html.erb
    <html lang="en" class="default-style">
    [After] app/views/layouts/application.html.erb
    <html lang="en" class="light-style">

  • ThemeSettings plugin settings are changed. Use Settings Panel Generator to get updated settings.

  • ThemeSettings.setMaterial() method is removed.
    Added ThemeSettings.setStyle(), ThemeSettings.isLightStyle(), ThemeSettings.isMaterialStyle(), ThemeSettings.isDarkStyle() methods.
    See Settings panel docs.

  • New style-dependent utility classes, which change its color depending on the current active style:

    • .theme-text-white - White (light or material style) / dark (dark style) text.
    • .theme-text-dark - Dark (light or material style) / white (dark style) text.
    • .theme-bg-white - White (light or material style) / dark (dark style) background.
    • .theme-bg-dark - Dark (light or material style) / white (dark style) background.
    • .theme-border-white - White (light or material style) / dark (dark style) border.
    • .theme-border-dark - Dark (light or material style) / white (dark style) border.

Changes in third-party components:

  • plyr changed its initialization method:

    Before
    plyr.setup('#selector', options);
    After
    new Plyr('#selector', options);

  • spinkit classes are changed. See https://github.com/tobiasahlin/SpinKit

  • SweetAlert's type option is renamed to icon.

    Before
    Swal.fire({
  ...,
  type: 'warning',
});
    After
    Swal.fire({
  ...,
  icon: 'warning',
});

  1. Server requirements for Ruby on Rails 6 was changed, see https://guides.rubyonrails.org/getting_started.html#installing-rails. Upgrade your environment regarding this.

    Official upgrade guide: https://guides.rubyonrails.org/upgrading_ruby_on_rails.html#upgrading-from-rails-5-2-to-rails-6-0.

  2. (Optional) Upgrade Node.js to 10.16 LTS and Yarn

  3. Copy new files and directories:

    postcss.config.js
babel.config.js
config/webpacker.yml
test/channels/
storage/
config/webpack/

  4. The build process was changed and now all vendor javascript files are built from original sources. All pre-compiled javascript files are removed. Regarding these changes, remove the next directories and copy the corresponding ones from the release:

    vendor/assets/javascripts/
vendor/assets/libs/*/

  5. Copy with replace changed files and directories:

    vendor/assets/stylesheets/bootstrap-material.scss
vendor/assets/stylesheets/bootstrap.scss
vendor/assets/stylesheets/rtl/bootstrap-material.scss
vendor/assets/stylesheets/rtl/bootstrap.scss
vendor/assets/stylesheets/migrate/appwork-130.scss
vendor/assets/stylesheets/_appwork/
vendor/assets/fonts/

  6. Copy with replace all files within appwork-v1_4_0/rails-turbolinks-starter/bin/ directory to your project's bin/.

  7. Update:

    Gemfile. Diff

    package.json. Diff

    .gitignore. Diff

    .ruby-version. Diff

    test/test_helper.rb. Diff

    app/assets/config/manifest.js. Diff

    app/jobs/application_job.rb. Diff

    app/views/layouts/application.html.erb. Diff

    config/application.rb. Diff

    config/cable.yml. Diff

    config/database.yml. Diff

    config/environments/development.rb. Diff

    config/environments/production.rb. Diff

    config/environments/test.rb. Diff

    config/initializers/assets.rb. Diff

    config/initializers/content_security_policy.rb. Diff

    config/puma.rb. Diff

    config/spring.rb. Diff

  8. Rails 6 introduced Webpacker asset builder. All files within the app/javascript/packs/ directory are processed by Webpack.

    • app/assets/javascripts/ directory is removed.
    • app/assets/javascripts/application.js => app/javascript/packs/application.js Diff
    • app/assets/javascripts/main.js => app/javascript/source/main.js Diff
    • app/assets/javascripts/cable.js => app/javascript/channels/index.js Diff 
    app/assets/javascripts/
    javascripts
    channels
    .keep
    application.js
    cable.js
    main.js
    app/javascript/
    javascript
    channels
    consumer.js
    index.js
    packs
    application.js
    source
    main.js
    main.scss

    Read more about Webpacker: https://github.com/rails/webpacker

  9. Update asset paths and asset helpers:

    • Use stylesheet_pack_tag and javascript_pack_tag instead of stylesheet_link_tag and javascript_include_tag
    • Changed vendor paths:

      • Javascript assets that start with vendor/ are resolved relative to vendor/assets/javascripts/ directory.

        <!-- PROJECT_ROOT/vendor/assets/javascripts/layout-helpers.js -->
<!-- Before: --><%= javascript_include_tag 'layout-helpers.js', 'data-turbolinks-track': 'reload' %>
<!-- After: --><%= javascript_pack_tag 'vendor/layout-helpers', 'data-turbolinks-track': 'reload' %>

      • Stylesheet assets that start with vendor/ are resolved relative to vendor/assets/stylesheets/ directory.

        <!-- PROJECT_ROOT/vendor/assets/stylesheets/bootstrap.css -->
<!-- Before: --><%= stylesheet_link_tag 'bootstrap.css', media: 'all', 'data-turbolinks-track': 'reload' %>
<!-- After: --><%= stylesheet_pack_tag 'vendor/bootstrap', media: 'all', 'data-turbolinks-track': 'reload' %>

<!-- PROJECT_ROOT/vendor/assets/stylesheets/rtl/theme-corporate.css -->
<!-- Before: --><%= stylesheet_link_tag 'rtl/theme-corporate.css', media: 'all', 'data-turbolinks-track': 'reload' %>
<!-- After: --><%= stylesheet_pack_tag 'vendor/rtl/theme-corporate', media: 'all', 'data-turbolinks-track': 'reload' %>

      • Font assets that start with vendor/fonts/ are resolved relative to vendor/assets/fonts/ directory.

        <!-- PROJECT_ROOT/vendor/assets/fonts/ionicons.css -->
<!-- Before: --><%= stylesheet_link_tag 'ionicons.css', media: 'all', 'data-turbolinks-track': 'reload' %>
<!-- After: --><%= stylesheet_pack_tag 'vendor/fonts/ionicons', media: 'all', 'data-turbolinks-track': 'reload' %>

      • Plugin assets that start with vendor/libs/ are resolved relative to vendor/assets/libs/ directory.

        <!-- PROJECT_ROOT/vendor/assets/libs/perfect-scrollbar/perfect-scrollbar.css -->
<!-- Before: --><%= stylesheet_link_tag 'perfect-scrollbar/perfect-scrollbar.css', media: 'all', 'data-turbolinks-track': 'reload' %>
<!-- After: --><%= stylesheet_pack_tag 'vendor/libs/perfect-scrollbar/perfect-scrollbar', media: 'all', 'data-turbolinks-track': 'reload' %>

<!-- PROJECT_ROOT/vendor/assets/libs/perfect-scrollbar/perfect-scrollbar.js -->
<!-- Before: --><%= javascript_include_tag 'perfect-scrollbar/perfect-scrollbar.js', 'data-turbolinks-track': 'reload' %>
<!-- After: --><%= javascript_pack_tag 'vendor/libs/perfect-scrollbar/perfect-scrollbar', 'data-turbolinks-track': 'reload' %>

    If you're using setup with settings panel, use starter template generator to see changes in app/views/layouts/application.html.erb.

  10. Remove Gemfile.lock

  11. Execute yarn upgrade

  12. Execute bundle install

Changes in third-party libraries:

  • bootstrap-multiselect plugin was removed.
  • bootstrap-sweetalert replaced with original sweetalert2 plugin. API isn't changed.
  • Shepherd.js changed its API. See rails-demo/app/javascript/packs/ui_tour.js for example. https://shepherdjs.dev/docs/tutorial-02-usage.html

  • Available extensions list of bootstrap-table package is changed (see rails-turbolinks-starter/vendor/assets/libs/bootstrap-table/extensions):

    Added extensions/cell-input
Removed extensions/group-by
Removed extensions/multi-column-toggle
Removed extensions/multiple-search
Removed extensions/multiple-selection-row
Removed extensions/select2-filter
Removed extensions/tree-column

  1. Copy with replace the next directories:

    vendor/assets/libs/bootstrap-sortable/
vendor/assets/libs/flot/
vendor/assets/libs/idletimer/

  2. Update:

    package.json. Diff

  3. Execute yarn install

  1. (Optional) Upgrade Node.js to 10.15 LTS and Yarn

  2. Copy new files and directories:

    vendor/assets/stylesheets/migrate/

  3. Copy with replace all SCSS files within vendor/assets/stylesheets/ and vendor/assets/stylesheets/rtl/ directories:

    vendor/assets/stylesheets/*.scss
vendor/assets/stylesheets/rtl/*.scss

  4. Copy with replace changed files and directories:

    vendor/assets/stylesheets/_appwork/
vendor/assets/stylesheets/_theme/
vendor/assets/stylesheets/_uikit/_social.scss
vendor/assets/stylesheets/pages/clients.scss
vendor/assets/stylesheets/pages/messages.scss
vendor/assets/javascripts/
vendor/assets/libs/
vendor/assets/fonts/

  5. Remove excluded libraries:

    vendor/assets/libs/bootstrap-tour/

  6. Since some extensions were removed from the bootstrap-table package, remove vendor/assets/libs/bootstrap-table/ directory and copy new appwork-v1_3_0/rails-starter/vendor/assets/libs/bootstrap-table/

  7. Update:

    config/autoprefixer.yml. Diff

    package.json. Diff

  8. Execute yarn upgrade

  9. (Optional) Upgrade Rails framework:

    Note: Possibly, you also will have to change ruby version in the Gemfile.

    1. Update:

      Gemfile. Diff

    2. Remove Gemfile.lock

    3. Execute bundle install

  10. Include polyfills in the <head> block after core stylesheets (see rails-starter-generator for example):

    <!-- Load polyfills -->
<%= javascript_include_tag 'polyfills.js', 'data-turbolinks-track': 'reload' %>
<script>document['documentMode']===10&&document.write('<script src="https://polyfill.io/v3/polyfill.min.js?features=Intl.~locale.en"><\/script>')</script>

  11. If you're using turbolinks, open app/assets/javascripts/main.js and add layoutHelpers.init() to the start of the turbolinks:load listener:

    ...
        
doc.addEventListener('turbolinks:load', function() {
  if (layoutHelpers) {
    layoutHelpers.init();
    ...
  }
  ...
})

...

  • Bootstrap CSS:

    Insert the following line into the config/initializers/assets.rb:

    Rails.application.config.assets.precompile += ['stylesheets/migrate/appwork-130.css']

    Include migration CSS file to the end of the <head> block:

    <%= stylesheet_link_tag 'migrate/appwork-130.css', media: 'all', 'data-turbolinks-track': 'reload' %>

    Remove this import after you correct all changed CSS classes in your HTML code.

    Changed classes: 

    .font-weight-thin → .font-weight-lighter
.text-dark → .text-body
.bg-none → .bg-transparent
.font-sans-serif → .text-sans-serif
.font-serif → .text-serif
.font-monospace → .text-monospace
.box-shadow-none → .shadow-none
.container-m--x → .container-m-nx
.container-m--y → .container-m-ny
.btn-round → .rounded-pill

Negative horizontal margins:
.m{sides}--{size} → .m{sides}-n{size}
.m{sides}-{breakpoint}--{size} → .m{sides}-{breakpoint}-n{size}

  • Bootstrap JS:

    All dropdown links must have href="#" attribute. Dropdown links with href="javascript:void(0)" will throw an error

  • Plugin API changed:

    Flot.js - See https://github.com/flot/flot/blob/master/CHANGELOG.md

    bootstrap-table - see demo examples

    Fullcalendar - See https://fullcalendar.io/docs

    bootstrap-sweetalert is deprecated, use Sweetalert2 instead. See - https://sweetalert2.github.io/

    bootstrap-tour library was removed, use "shepherd" tour library instead. See - https://shipshapecode.github.io/shepherd/

Note: Validation icons are disabled by default. To enable it, add the next variable in the vendor/assets/stylesheets/_custom-variables/_appwork.scss and vendor/assets/stylesheets/_custom-variables/_appwork-material.scss: 

$enable-validation-icons: true;

  1. Update package.json. Diff

  2. Copy with replace changed files and directories:

    vendor/assets/javascripts/
vendor/assets/libs/
vendor/assets/fonts/fontawesome/
vendor/assets/fonts/ionicons/ionicons/
vendor/assets/fonts/fontawesome.css.erb
vendor/assets/fonts/ionicons.css.erb
vendor/assets/stylesheets/_appwork/_accordion.scss
vendor/assets/stylesheets/_appwork/_breadcrumb.scss
vendor/assets/stylesheets/_appwork/_buttons.scss
vendor/assets/stylesheets/_appwork/_close.scss
vendor/assets/stylesheets/_appwork/_custom-forms.scss
vendor/assets/stylesheets/_appwork/_mixins.scss
vendor/assets/stylesheets/_appwork/_switcher.scss
vendor/assets/stylesheets/_appwork/_variables-material.scss
vendor/assets/stylesheets/_appwork/_variables.scss
vendor/assets/stylesheets/colors-material.scss

  3. Execute yarn install