glass-vnext

Glass [DRAFT v0.1 - 2016-04-26]

Glass is a basic starter theme integrated with the Material API. Demo store - coming soon.

1. Getting Started
   1. Requirements
   2. 1. Get the Glass Theme
   3. 2. Set Up the Upstream Repo
   4. 3. Install the Project Dependencies
   5. 4. Start Up Your Local Dev Environment
2. Glass Theme Directory Structure
   1. Included Third-Party Components
3. Store Editor Settings
   1. Content Settings
      1. sections.json
   2. theme-settings-navigation.json
      1. page Values
   3. application.json
   4. Coming Soon
4. Running Locally
5. Release Process

Getting Started

Requirements

• git
• node v4+ (preferably via nvm)
• npm v2+
• familiarity with AngularJS 1

1. Get the Glass Theme

Download the latest Glass release, or clone the repo:

git clone https://github.com/volusion/Material-Docs.git

2. Set Up the Upstream Repo

Manage your files on your account while keeping your files up to date with ours.

Configure the Glass repo's shortname and the reference URL. We'll use upstream in our example:

git remote add upstream https://github.com/volusion/Material-Docs.git

Check to see if you've added upstream successfully:

git remote -v

You'll see a list of shortnames and the reference URLs that are configured:

origin  https://github.com/MaterialDev/glass.git (fetch)
origin  https://github.com/MaterialDev/glass.git (push)
upstream    https://github.com/volusion/Material-Docs.git (fetch)
upstream    https://github.com/volusion/Material-Docs.git (push)

3. Install the Project Dependencies

If you've downloaded the repo, open a terminal (OS X/Linux) or command prompt (Windows).

1. Navigate to the root of your theme directory.
2. Run npm install.

Note: If you get an error, refer to the Troubleshooting Guide

4. Start Up Your Local Dev Environment

Run npm start.

Glass Theme Directory Structure

The primary files you use to develop themes have the following structure:

glass/
    app/
	├── components/
	│   ├── featured-products/
	│   │   ├── featured-products.directive.html
	│   │   └── featured-products.directive.js
	│   ├── footer/
	│   │   ├── copyright.component.js
	│   │   ├── footer.component.js
	│   │   ├── footer.html
	│   │   ├── footer.less
	│   │   ├── links-list.component.js
	│   │   └── social-icons.component.js
	│   ├── header/
	│   │   ├── cart-summary.component.js
	│   │   ├── header.component.js
	│   │   ├── header.html
	│   │   ├── header.less
	│   │   └── search-form.component.js
	│   ├── menu/
	│   │   └── menu.less
	│   ├── product-card/
	│   │   ├── product-card.directive.html
	│   │   ├── product-card.directive.js
	│   │   └── product-card.less
	│   ├── product-grid/
	│   │   ├── product-grid.directive.html
	│   │   ├── product-grid.directive.js
	│   │   └── product-grid.less
	│   ├── product-slideshow/
	│   │   ├── product-slideshow.directive.html
	│   │   ├── product-slideshow.directive.js
	│   │   └── product-slideshow.less
	│   ├── product-sort/
	│   │   ├── product-sort.constant.js
	│   │   ├── product-sort.directive.html
	│   │   ├── product-sort.directive.js
	│   │   └── product-sort.less
	│   ├── product-variants/
	│   │   ├── product-variants.directive.html
	│   │   ├── product-variants.directive.js
	│   │   └── product-variants.less
	│   ├── product-zoom/
	│   │   └── product-zoom.less
	│   ├── mobile-nav/
	│   │   ├── mobile-nav.directive.html
	│   │   ├── mobile-nav.directive.js
	│   │   └── mobile-nav.less
	│   └── slideshow/
	│       ├── slideshow.directive.html
	│       ├── slideshow.directive.js
	│       └── slideshow.less
	├── configuration.js
	├── images/
	│   └── favicon.ico
	├── index.html
	├── index.mustache
	├── pages/
	│   ├── 404/
	│   │   ├── 404.html
	│   │   ├── 404.less
	│   │   └── error-404-page.component.js
	│   ├── category/
	│   │   ├── category-info/
	│   │   │   ├── category-desc.component..js
	│   │   │   ├── category-image.component.js
	│   │   │   ├── category-info.component.js
	│   │   │   ├── category-name.component.js
	│   │   │   └── sub-category-list.component.js
	│   │   ├── category.component.js
	│   │   ├── category.html
	│   │   └── category.less
	│   ├── content-page/
	│   │   ├── content-page.component.js
	│   │   ├── content-page.html
	│   │   └── content-page.less
	│   ├── home/
	│   │   ├── hero.component.js
	│   │   ├── home.component.js
	│   │   ├── home.html
	│   │   └── home.less
	│   ├── product/
	│   │   ├── components/
	│   │   │   ├── product-breadcrumb.component.js
	│   │   │   ├── product-images.component.js
	│   │   │   └── related-products.component.js
	│   │   ├── product-info/
	│   │   │   ├── add-to-cart.component.js
	│   │   │   ├── product-extended-desc.component.js
	│   │   │   ├── product-info.component.js
	│   │   │   ├── product-long-desc.component.js
	│   │   │   ├── product-name.component.js
	│   │   │   ├── product-price.component.js
	│   │   │   └── product-quantity.component.js
	│   │   ├── product.html
	│   │   ├── product.less
	│   │   └── product-details.component.js
	│   └── search-results/
	│       ├── search-results.component.js
	│       ├── search-results.html
	│       └── search-results.less
	│   ├── main-layout.html
	│   ├── main-layout.component.js
	│   └── pages.routes.js
	├── settings/
	│   ├── application.json
	│   ├── cat.less
	│   ├── sections.json
	│   ├── style-settings.json
	│   ├── style-settings.less
	│   └── theme-settings-navigation.json
	├── styles
	│   ├── base
	│   │   ├── base.less
	│   │   ├── bootstrap/
    │   │   └── custom-mixins/
    │   ├── main.css
	│   └── main.less
	├── translations/
	├── _constants.js
	├── app.js
    ├── configuration.js
	├── images
	│   └── favicon.ico
	├── index.html
	├── index.mustache
	├── robots.txt
	└── template.js

Included Third-Party Components

• Bootstrap 3
• Angular Material
• UI Bootstrap
• More third-party libraries
  • package.json
  • bower.json

Store Editor Settings

The primary files that determine the store editor settings are located in the settings directory:

• sections.json
• application.json
• theme-settings-navigation.json
• style-settings.json

Store editor settings determine options for your site such as default fonts, theme colors, content types, and more.

Setting Type	Description
Content	A collection of content settings, such as default sort options, number of products to display, cart style and more.
Style	A variety of style settings, such as font-family, font size, text color, link colors, and more.

Content Settings

This guide walks you through adding editable controls for your theme's content settings. For this example, we'll use a simplified version of the banner on the Montreal theme.

sections.json

This file contains a collection of editable controls that allow merchants to configure theme settings through the Store Editor. In sections.json, you set up editable sections, such as a banner or slideshow, to build the menus and editable controls that merchants can later configure by going to Dashboard > Store Editor > Content, clicking on the page section and selecting the category. The following code is an example of options that show up under the "Main Banner" category for content settings:

"banner": {
    "id": "banner",                     // section-id
    "title": "Main Banner",             // section title
    "settings": [{
        "id": "title",
        "label": "Title",
        "type": "text"                  // editable control
    },{
        "id": "buttonText",
        "label": "Button Text",
        "type": "text"                  // editable control
    },{
        "id": "buttonLink",
        "label": "Button Link",
        "type": "link"                  // editable control
    },{
        "id": "textAlign",
        "label": "Text Align",
        "type": "complex-dropdown",     // editable control
        "values": [{                    // options to display in drop down
            "display": "Left",
            "value": "left"
        }, {
            "display": "Center",
            "value": "center"
        }, {
            "display": "Right",
            "value": "right"
        }]
    },{
        "id": "backgroundImage",
        "label": "Image",
        "type": "image-single"         // editable control
    }]
}

HTML

<div editable-section section-id="banner">
    <div ng-style="{ 'background-image':'url(' + settings.backgroundImage.fullUri + ')'}" ng-class="{ 'text-left': settings.textAlign == 'left', 'text-center': settings.textAlign == 'center', 'text-right': settings.textAlign == 'right' }">
        <h1>{{settings.title}}</h1>
        <a ng-href="{{settings.buttonLink.url}}" title="{{ settings.buttonText }}">{{settings.buttonText}}</a>
    </div>
</div>

Editable Controls

Material has a library of editor controls that you can use to build editable content. View the editor control examples.

type	Returns	Description
image-single	object	Image library and image editor UI
image-slides	object	Multiple image input with URL and alt text
product	product id	Product picker with autocomplete
productId-multi	product id's	Product picker with autocomplete, allows multiple selections
link	string	Link picker that selects from the sites categories, products and pages; with autocomplete; allows custom URLs
text	string	Single-line text input
text-multiline	string	Multi-line text input
toggle	boolean	Switch
dropdown	number	Drop-down list of defined values
complex-dropdown	string	Drop-down list of defined values

theme-settings-navigation.json

To make the sections.json settings accessible to the rest of your theme, add the settings to the children object in theme-settings-navigation.json, within the page in which it appears. For example, if you added a couple of editable-sections to sections.json named banner and promos–and they only appear on the homepage–you would add these settings to theme-settings-navigation.json as follows:

{
    "home":[{                               // page
        "id": "home",                       // theme-section id
        "label": "Home",
        "type": "category",
        "children": [{
            "id": "banner",                 // editable-section id
            "type": "editable-section"
        },
        {
            "id": "promos",                 // editable-section id
            "type": "editable-section"
        }]
    }]
}

page Values

• home
• category
• product
• search
• notfound

application.json

This file is where you provide default theme content for cases when merchants do not provide content of their own. The following code is an example of content that shows up under the Home > Main Banner panel for content settings:

"banner": {
    "id": "banner",
    "settings": {
        "title": "Cookware & Cutlery",
        "buttonText": "Save Now",
        "buttonUrl": {
            "url": ""
        },
        "textAlign": "center",
        "backgroundImage": {
            "fullUri": "//montreal.mymaterial.com/main-banner.jpg"
        }
    }
}

Coming Soon

• Style Settings
• Contributing Guildelines
• Theme Requirements
  • Admin UI Checklist
  • Theme Files Checklist
• Additional Resources

Running Locally

1. npm install
2. put your tenantId in gulp/config.json
3. run gulp

Release Process

1. git pull --rebase
2. git push (if any local outstanding commits when working in develop, otherwise make sure your pull request has been merged)
3. npm install (until it works. when troubleshooting you may also want to rm -rf node_modules/ )
4. gulp (until loads in browser)
5. rm -rf bower_components && bower i
6. gulp inject
7. until gulp cat-less ; do echo "Retrying..." ; done
8. gulp deploy (deploys it to dev)
9. test in store on dev
10. look for dist/deploy.zip, you may need to run gulp zip to generate it
11. deploy to production: log in to MARS (VPN required if off site) hit New Version, upload deploy.zip