07 Themes - ecellar/remote-widgets GitHub Wiki

The eCellar Designer Widgets system comes with a CSS theme that styles all of the HTML templates used by the SPA. The theme is designed to inherit as much of your site’s styling as possible, while also providing nice, mobile-first, styling for things that are specific to the Designer Widgets.

To best understand our theme, it’s good to know how the HTML templates work and to get a little bit familiar with how we use our CSS classes in the templates.

You can learn about templates at our 08 HTML Templates page.

You can view a list of all templates at our 12 Template Directory page.

Naming

Classes used in our theme all start with “ecp”, which is short for “e-cellar-public”. As long as you are not also using the same class names that we are, our html and styling should:

a) Allow your site’s own styles to “flow down” nicely, via inheritance.
b) Add additional styling for our components (not affecting anything in your site).

Core and Components

Our CSS classes are split into two logical “categories”:

1. “core” styles: these are styles used throughout the templates

2. “component” styles: these are component-specific styles

In general, the core styles cover most of the styling across all templates. For cases where it made sense for us to create component-specific styles, we did so, but usually they are minor overrides of some core styles.

A component name is used in the outermost HTML element in all main HTML templates.

For example:

<div class="ecp-component ecp_CategoryWithProducts">

There we have two classes from our theme:

.ecp-component
.ecp_CategoryWithProducts

The .ecp-component class is a core class. The .ecp_CategoryWithProducts class is a component class.

Component classes are prefixed with ecp_, followed by the name of the template that they are styling. For example, this template:

CategoryWithProducts

Has the ecp_CategoryWithProducts class in it’s outermost HTML element. We can use the .ecp_CategoryWithProducts class to provide component-specific styling.

For example:

.ecp_CategoryWithProducts h3 { line-height: 1.4; margin-bottom: 0; }
.ecp_CategoryWithProducts .ecp-list-item { margin-bottom: 2rem; }

Note: we do not use any #id selectors in our theme.

Overriding Styles

In general, if you want to alter any of the styling that comes from our theme, an easy and fast way to do so is by creating a separate CSS file of your own with overrides in it, then loading that after ours.

For example, by default we do not provide any top margin or padding for the .ecp-component class. All main templates have that class in their outermost HTML element. So if you want to add some top margin for all components, you could put something like this in your override file:

.ecp-component { margin-top: 1rem; }

Note: we use rem for all spacing and sizing. We do not use em nor px unless a very specific situation required it.

See 01 Getting Started for information about loading our theme.

When we release new features, we sometimes add new styles to our default theme. If you copy our theme and load your copy instead of linking to our theme and overriding the defaults you WILL NOT automatically get the new styles for the new functionality. We strongly recommend against that.

We minify our CSS theme file for use by your site. For example:

ecp-theme.css

If you want to, you can run that through a “CSS beautifier” to view a more readable version of the CSS. However, the minify process also strips out all comments from our original .css files. Because of that, we have also made our source CSS available here:

ecp-theme.css source

Our theme includes one image that is used by our “UI blocker”. It’s an animated gif, referenced in our core CSS:

.ecp-ui-block {
    background: url('../img/block_spinner_32.gif') 50% 50% no-repeat rgba(0,0,0,0.45);
  }

View the file

The theme does not have any other image files.

There are no icons in our theme. If you would like to add icons to any of the templates, you can do so by customizing the templates and/or CSS and using your own images, Font Awesome, etc.

A common first customization is to create a custom MiniCart template that includes a “cart” image or icon.

Visit the 09 Custom Templates page to learn about creating custom templates.

If you decide that you would like to scrap our CSS theme and create your own, you may do that. You may also create your own set of custom templates, with or without our class names in them. You have the freedom to do all of that.

It’s worth mentioning, though, that you would be taking on a lot of work and you might find that many of the templates are not ones worth messing with. For example, the Account templates cover a lot of ground. If you don’t load our theme, you will need to review each template and make decisions on how to style them.

For these reasons, we recommend approaching customizations on a one-by-one basis: first see what you can do with CSS overrides, then consider custom templates.