B2B theme for VirtoCommerce Storefront

B2B theme for VirtoCommerce Storefront used by B2B-Store sample store. It is a showcase for b2b features support of VirtoCommerce.

Main article: theme development on virtocommerce.com/docs

CMS Content folder structure

Getting started

1. Install prerequisites.
2. Clone repo.
   1. In Visual Studio, go to Team Explorer → Clone → Enter https://github.com/VirtoCommerce/vc-theme-b2b.git as URL and C:\vc-theme-b2b (for example) as path.
   2. Or execute command

      git clone https://github.com/VirtoCommerce/vc-theme-b2b.git "C:\vc-theme-b2b"
      

      (where C:\vc-theme-b2b is path to folder where you want to clone repo).
3. Link you theme repo to store. Execute:

   mklink /d "C:\vc-platform\VirtoCommerce.Platform.Web\App_Data\cms-content\Themes\B2B-Store\default" "C:\vc-theme-b2b"
   

   (where C:\vc-platform\VirtoCommerce.Platform.Web\App_Data\cms-content is path to CMS content storage configured at platform & storefront deployment steps, 'B2B-Store' is your store name and 'C:\vc-theme-b2b' is path to your theme repo).
4. Open theme folder in your IDE
   1. In Visual Studio (including 2017) go to File → Open → Website
   2. In Visual Studio Code, go to File → Open → Folder
   3. Select C:\vc-theme-b2b (where C:\vc-theme-b2b is path to folder where you want to clone repo) and open it.
5. Install Node.js dependencies.
   1. In Visual Studio all dependencies will be installed automatically. Just wait a few minutes.
   2. In Visual Studio Code and other editors, you need to run

   npm install
   

   to install Node.js dependencies.

Prerequisites

Storefront

You need to have local installation of storefront. Follow this article step-by-step to install storefront from binaries or source code.

Visual Studio 2015.3 and above (up to Visual Studio 2017.3 at least)

If you have Visual Studio 2015 with Update 3 and above, you don't need install any prerequisites. Latest versions of Node.js and Gulp already included in your Visual Studio installation and supported in built-in Task Runner Explorer.

Visual Studio from 2015 up to 2015.2

Task Runner Explorer, Node.js and Gulp already included in your Visual Studio installation. However, you need update your Node.js to at least 4.0.0.

1. Update Node.js to v4.0.0 at least (we recommend latest LTS version). Use C:\Program Files\nodejs installation path (change Program Files to Program Files (x86) on 64-bit machine).
2. Add Node.js installation path to External Web Tools or move $(PATH) to top:

Visual Studio from 2013.3 up to 2013.5

You need install:

1. Task Runner Explorer Visual Studio extension
2. Install Node.js v4.0.0 or above (we recommend latest LTS version)

3. npm install gulp -g
   

Visual Studio Code and other editors

1. Install Node.js v4.0.0 or above (we recommend latest LTS version)

2. npm install gulp -g
   

Node.js starting from 8.0

Execute the following command: npm install --global --production windows-build-tools

Liquid reference

Liquid is the templating engine that powers Virto Commerce templates. Go to Liquid documentation.

Bundling & minification

Main article: bundling & minification on virtocommerce.com/docs

Bundling is a technique you can use to improve request load time. Bundling improves load time by reducing the number of requests to the server (assets such as CSS and JavaScript will be combined to single file per file format).

How bundling and minification works

How to add bundle to layout

{% raw %}{{ 'bundle/scripts.js' | static_asset_url | append_version | script_tag }}{% endraw %}

• static_asset_url means that this file is static content of site
• script_tag or stylesheet_tag will generate

  <script ... >
  

  or

  <link rel="stylesheet" ... >
  

• append_version is used to correctly invalidate browser cache for bundles. It calculate hash of file and append it as part of query string in url. Make sure that it's added after static_content_url (or other url filter), not after script_tag, stylesheet_tag (or other html tags).

Bundling and minification process workflow

When you run the default task to bundle & minify theme, the following happens:

1. ESLint runs and output warnings and errors in javascript code.
2. Javascript minifies and source maps generates.
3. CSS processes by Autoprefixer with the following browsers support (documentation may be sometimes outdated; browser versions specified in gulpfile then specified in docs, not vice versa).
4. CSS minifies and source maps generates.

IDE configuration

Visual Studio (any version)

Bundling & minification will work automatically when you save file and on build.

Visual Studio Code

Bundling & minification will work automatically on build. If you want to automatically bundle & minify files on save, please, install & configure Blade Runnner Visual Studio Code extension.

Other editors

Run

gulp watch

on command line if you want to bundle & minify files on save or run

gulp default

manually when you need to bundle & minify theme files.

Tips & tricks

Attention: while theme including bundlesconfig.json file, you must not use Bundler & Minifier Visual Studio extension with theme. We're using gulp to bundle & minify files on theme, because it support a lot of possible customizations and has a plugins for css minification and correct source maps generation. Wrong source map generation and lack of css minification is a primary reason why we do not use Bundler & Minifier extension in Visual Studio.

Tip: if bundling & minification failed, you, probably, need to run gulp watch task manually after that. In Visual Studio, go to Task Runner Explorer and click Run on task watch. In Visual Studio Code go to Command Palette (Ctrl+Shift+P) and type

task watch

then press Enter.

The following gulp tasks available to you:

1. default: default task. Bundles and minifies theme files.
2. clean: removes bundled & minified files.
3. lint: runs eslint to check for warnings & errors in javascript files. Look at eslint site for details.
4. min and min:js, min:css, min:html: minify all or specified types of files.
5. watch: watching to any changes on bundled & configuration files and update bundles when any change occurs.
6. compress: creates zip package with all needed files to deploy theme on storefront.

How to localize theme

Main article: how to localize theme on virtocommerce.com/docs

Adding new translation to theme

Storefront theme localization is very similar to VirtoCommerce Platform localization. Check it for details on working with translation files.

1. Make a copy of <theme repository location>\locales\en.default.json file
2. Rename the copied file to begin with your needed language 2 letter code (e.g., "es.default.json").
3. Translate the file content.

Adding new language to store

1. Open your store in VirtoCommerce Platform ( More → Browse → Stores → <your store> ).
2. Check whether your language exists in the "Additional languages" available values list or add it in case it's missing:

License

Copyright (c) Virto Solutions LTD. All rights reserved.

Licensed under the Virto Commerce Open Software License (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://virtocommerce.com/opensourcelicense

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.