Look and design
Change the store layout
Ecwid integration code provides a number of modifications to the store layout: number of products per row, default view mode and more. See the details below.
Add new element to products in category pages
Add new element to product in product listing
Ecwid.OnPageLoaded.add(function (page) {
// Apply changes only to category pages
if (page.type == 'CATEGORY') {
// Remove any previously added elements when new page changes
// If you change class name here, make sure to update it below too
var removingButtons = document.getElementsByClassName('custom_app_button');
for (i = removingButtons.length - 1; i >= 0; i--) {
removingButtons[i].parentNode.removeChild(removingButtons[i]);
}
// Loop to add new element to each product in product listing
for (i = 0; i < document.querySelectorAll('.grid-product').length; i++) {
var elem = document.querySelector('.grid-product:nth-child(' + (i + 1) + ') .grid-product__wrap-inner');
// Create our custom element
var container = document.createElement("div");
// Set custom class to locate our new element
// If you change class name here, make sure to update it above too
container.setAttribute('class', 'custom_app_button');
// Change vertical order position of new element using 'order' value. Bigger = lower; smaller = higher
container.setAttribute('style', 'order: 6; padding:0;');
// Set the content of our new element
container.innerHTML = '<div><div class="label label--flag label--success"><div class="label__text">Sale 2018</div></div></div>';
// (OPTIONAL) Show alert when user clicks on new container
container.addEventListener("click", function (event) {
event.stopImmediatePropagation();
alert('SALE MESSAGE');
});
// Add new element to products
elem.appendChild(container);
}
}
})
Check how to add new elements to products in product listing in example displayed on the right.
How to enable latest version of product listing in your test store
Adapt storefront layout to changed container width
By default, Ecwid is a responsive widget which adapts to the changing screen width. That’s usually when the container for storefront changes its width also.
However, if the screen width stays the same but the container for storefront changes its width, you will need to call the Ecwid.resizeProductBrowser()
function to adapt Ecwid’s layout to this change.
Change the number of products/categories on a page
Add Ecwid storefront to your website
<div id="my-store-1003"></div><div> <script type="text/javascript" src="https://app.ecwid.com/script.js?1003" charset="utf-8"></script><script type="text/javascript"> xProductBrowser("categoriesPerRow=3","views=grid(3,3) list(10) table(20)","categoryView=grid","searchView=list","id=my-store-1003");</script></div>
Find the following code in the widget code on the right:
"categoriesPerRow=3","views=grid(3,3) list(10) table(20)","categoryView=grid","searchView=list"
This code defines products and categories listing styles. Let’s see its parts:
"categoriesPerRow=3"
– defines number of categories per row"views=grid(3,3) list(10) table(20)"
- defines the available views and their settings. If you want to remove any view, just remove thegrid(3,3)
orlist(10)
ortable(20)
text from the settings.
The number in braces is number of products in the particular view. I.e.:
grid(K,L)
-K
is a number of products in a column,L
- number of products in a row in grid viewlist(M)
-M
is a number of products on one page in list viewtable(N)
-N
is a number of products on one page in table view
Default view mode settings:
"categoryView=grid"
- defines the default view for products in categories. Possible values:list
,grid
,table
"searchView=list"
- defines the default view for search results. Possible values:list
,grid
,table
.
Feel free to change the code to achieve the layout you need!
Set default product or category page
Open “Surfboards” category of Ecwid Demo store by default
<div>
<script type='text/javascript' src='https://app.ecwid.com/script.js?1003'></script>
<script type='text/javascript'> xProductBrowser("categoriesPerRow=3","views=grid(3,3) list(10) table(20)","categoryView=grid","searchView=list","style=","defaultCategoryId=20671017"); </script>
</div>
Open “PYZEL Amigo 6'2 Surfboard” product in Ecwid Demo store by default
<div>
<script type='text/javascript' src='https://app.ecwid.com/script.js?1003'></script>
<script type='text/javascript'> xProductBrowser("categoriesPerRow=3","views=grid(3,3) list(10) table(20)","categoryView=grid","searchView=list","style=","defaultProductId=70178249"); </script>
</div>
By default, the storefront widget opens with a list of root category. But you can configure it to show a different category or a particular product when user opens it for the first time.
You can do it by adding either option to the Product Browser integration code:
"defaultCategoryId=%categoryId%"
or
"defaultProductId=%productId%"
The example codes are available on the right.
Show or hide storefront elements
Using additional configuration code you are able to hide some storefront elements without any CSS rules. These settings will override user preferences set in the Ecwid Control Panel.
Place the codes anywhere on a page where Ecwid integration code is added to apply them.
Hide sign in link
<script>
window.ec = window.ec || Object();
window.ec.storefront = window.ec.storefront || Object();
window.ec.storefront.show_signin_link = false; // hides the sign in link
</script>
Hide the sign in link for customers in a store using the code example on the right. Place the codes anywhere on a page where Ecwid integration code is added to apply them.
The config window.ec.storefront.show_signin_link
accepts two values: true
to show the sign in link, and false
to hide it.
Hide breadcrumbs
<script>
window.ec = window.ec || Object();
window.ec.storefront = window.ec.storefront || Object();
window.ec.storefront.show_breadcrumbs = false; // hides the breadcrumbs
</script>
Hide the storefront breadcrumbs for customers using the code example on the right. Place the codes anywhere on a page where Ecwid integration code is added to apply them.
The config window.ec.storefront.show_breadcrumbs
accepts two values: true
to show the breadcrumbs, and false
to hide them.
Hide ‘View as’ and 'Sort by’ options in product listing
<script>
window.ec = window.ec || Object();
window.ec.storefront = window.ec.storefront || Object();
window.ec.storefront.product_list_show_sort_viewas_options = false; // hides the 'View as' and 'Sort by' options
</script>
Hide the options to 'View as’ and 'Sort by’ products for customers using the code example on the right. Place the codes anywhere on a page where Ecwid integration code is added to apply them.
The config window.ec.storefront.product_list_show_sort_viewas_options
accepts two values: true
to show the 'View as’ and 'Sort by’ options, and false
to hide them.
Hide 'Qty’ selection in product details
<script>
window.ec = window.ec || Object();
window.ec.storefront = window.ec.storefront || Object();
window.ec.storefront.product_details_show_qty = false; // hides the 'Qty' selection
</script>
Hide the 'Qty’ section for customers in product details using the code example on the right. Place the codes anywhere on a page where Ecwid integration code is added to apply them.
The config window.ec.storefront.product_details_show_qty
accepts two values: true
to show the 'Qty’ section, and false
to hide it.
Hide 'In stock’ label in product details
<script>
window.ec = window.ec || Object();
window.ec.storefront = window.ec.storefront || Object();
window.ec.storefront.product_details_show_in_stock_label = false; // hides the 'In stock' label
</script>
Hide the 'In stock’ label for customers in product details using the code example on the right. Place the codes anywhere on a page where Ecwid integration code is added to apply them.
The config window.ec.storefront.product_details_show_in_stock_label
accepts two values: true
to show the 'In stock’ label, and false
to hide it.
Hide number of items in stock in product details
<script>
window.ec = window.ec || Object();
window.ec.storefront = window.ec.storefront || Object();
window.ec.storefront.product_details_show_number_of_items_in_stock = false; // hides the number of items in stock
</script>
Hide the number if items in stock for customers in product details using the code example on the right. Place the codes anywhere on a page where Ecwid integration code is added to apply them.
The config window.ec.storefront.product_details_show_number_of_items_in_stock
accepts two values: true
to show the number of items in stock, and false
to hide it.
Center popups in iframe storefronts
Example of centering popups
<script src='https://d1e443hvef5jf2.cloudfront.net/static/iframeintegration.js'></script>
<script type='text/javascript'>
window.addEventListener('load', function(e) {
setupEcwidPopupCentering('#myframe');
});
</script>
Ecwid can be embedded to a website in many ways. Sometimes a storefront can be inserted in an iframe container due to the limitations of a platform. To make sure that all popup windows such as customer account login popup are displayed in the center of an iframe, use the example code on the right in a main frame of your page.
setupEcwidPopupCentering()
function accepts one argument, which is the ID of an iframe element, where Ecwid storefront is loaded. In order to work, setupEcwidPopupCentering()
function needs to have iframeintegration.js
file loaded for that frame.
Product listing
<script>
window.ec = window.ec || Object();
window.ec.storefront = window.ec.storefront || Object();
window.ec.storefront.enable_new_product_list = true;
</script>
The recent version of product listing allows for more customization and better looking storefronts across all Ecwid stores. You can enable it in your Ecwid store using the example code on the right.
Customizing product listing
Check out all the customization options for the product listing available out of the box below.
If you apply any of the changes below after storefront has loaded, you can update its look on the fly using the Ecwid.refreshConfig()
function.
Adding new elements to product listing
Ecwid’s latest version of product listing (category pages) works in a different way, which requires different approach to adding new elements to a page.
Check this page for code example: Add new element to products in category pages
Control display mode of product title in product listing
<script>
window.ec = window.ec || Object();
window.ec.storefront = window.ec.storefront || Object();
window.ec.storefront.product_list_title_behavior = "SHOW_ON_HOVER"; // show product title on hover
</script>
Control the way product title is displayed in product listing (category pages).
Possible values: "SHOW"
, "HIDE"
, "SHOW_ON_HOVER"
.
If you apply the change after storefront has loaded, you can update its look on the fly using the Ecwid.refreshConfig()
function.
Control display mode of SKUs in product listing
<script>
window.ec = window.ec || Object();
window.ec.storefront = window.ec.storefront || Object();
window.ec.window.ec.storefront.product_list_sku_behavior = "HIDE"; // hide product SKU in product listing
</script>
Control the way product SKU is displayed in product listing (category pages).
Possible values: "SHOW"
, "HIDE"
, "SHOW_ON_HOVER"
.
If you apply the change after storefront has loaded, you can update its look on the fly using the Ecwid.refreshConfig()
function.
Control display mode of prices in product listing
<script>
window.ec = window.ec || Object();
window.ec.storefront = window.ec.storefront || Object();
window.ec.storefront.product_list_price_behavior = "HIDE"; // hide product SKU in product listing
</script>
Control the way product price is displayed in product listing (category pages).
Possible values: "SHOW"
, "HIDE"
, "SHOW_ON_HOVER"
.
If you apply the change after storefront has loaded, you can update its look on the fly using the Ecwid.refreshConfig()
function.
Control display mode of 'Buy now’ buttons in product listing
<script>
window.ec = window.ec || Object();
window.ec.storefront = window.ec.storefront || Object();
window.ec.storefront.product_list_buybutton_behavior = "HIDE"; // hide product SKU in product listing
</script>
Control the way 'Buy now’ buttons are displayed in product listing (category pages).
Possible values: "SHOW"
, "HIDE"
, "SHOW_ON_HOVER"
.
Important: the 'Buy now’ button must first be enabled in the Ecwid Control Panel > Settings > General > Cart > Show “Buy now” buttons on products list pages
If you apply the change after storefront has loaded, you can update its look on the fly using the Ecwid.refreshConfig()
function.
Control the size of images in product listing
<script>
window.ec = window.ec || Object();
window.ec.storefront = window.ec.storefront || Object();
window.ec.storefront.product_list_image_size = "LARGE"; // set large product image size in product listing
</script>
Control the size of product image in product listing (category pages).
Possible values: "SMALL"
, "MEDIUM"
, "LARGE"
.
If you apply the change after storefront has loaded, you can update its look on the fly using the Ecwid.refreshConfig()
function.
Control the aspect ratio of images in product listing
<script>
window.ec = window.ec || Object();
window.ec.storefront = window.ec.storefront || Object();
window.ec.storefront.product_list_image_aspect_ratio = "PORTRAIT_075"; // set portrait aspect ratio for images in product listing
</script>
Control the aspect ratio of product image in product listing (category pages).
Possible values: "PORTRAIT_0667"
, "PORTRAIT_075"
, "SQUARE_1"
, "LANDSCAPE_1333"
, "LANDSCAPE_15"
.
If you apply the change after storefront has loaded, you can update its look on the fly using the Ecwid.refreshConfig()
function.
Apply shadow effect for images in product listing
<script>
window.ec = window.ec || Object();
window.ec.storefront = window.ec.storefront || Object();
window.ec.storefront.product_list_image_has_shadow = false; // hide shadow effect for product images
</script>
Show or hide the shadow effect for product images in product listing (category pages). If true
, it also makes images slightly darker to make them stand out against the white background.
Possible values: true
, false
.
If you apply the change after storefront has loaded, you can update its look on the fly using the Ecwid.refreshConfig()
function.
Show additional image on hover in product listing
<script>
window.ec = window.ec || Object();
window.ec.storefront = window.ec.storefront || Object();
window.ec.storefront.product_list_show_additional_image_on_hover = true; // show additional image on hover
</script>
Show or hide the additional image on hover in product listing (category pages).
Possible values: true
, false
.
If you apply the change after storefront has loaded, you can update its look on the fly using the Ecwid.refreshConfig()
function.
Show frame / border for products in product listing
<script>
window.ec = window.ec || Object();
window.ec.storefront = window.ec.storefront || Object();
window.ec.storefront.product_list_show_frame = true; // show frame / border for products
</script>
Show or hide the frame / border for products in product listing (category pages).
Possible values: true
, false
.
If you apply the change after storefront has loaded, you can update its look on the fly using the Ecwid.refreshConfig()
function.
Set align of SKU, price, name in product listing
<script>
window.ec = window.ec || Object();
window.ec.storefront = window.ec.storefront || Object();
window.ec.storefront.product_list_product_info_layout = "LEFT"; // align name/sku/price to the left
</script>
Set align of sku/price/name section in product listing (category pages). Works for name/sku/price shown below the image. Doesn’t apply to name/sku/price shown on hover.
Possible values: "CENTER"
, "LEFT"
, "JUSTIFY"
, "RIGHT"
.
If you apply the change after storefront has loaded, you can update its look on the fly using the Ecwid.refreshConfig()
function.
Set custom breadcrumbs separator in product listing
<script>
window.ec = window.ec || Object();
window.ec.storefront = window.ec.storefront || Object();
window.ec.storefront.breadcrumbs_separator = "/"; // set breadcrumbs separator as '/', so it will look like: Store / Shoes / Children
</script>
Set custom breadcrumbs separator in product listing (category pages). For example: Store / SubCategory / SubSubCategory
or Store -> SubCategory -> SubSubCategory
or any other custom string.
Possible values: any string, e.g. "/"
, "*"
, "->"
, etc.
If you apply the change after storefront has loaded, you can update its look on the fly using the Ecwid.refreshConfig()
function.
Set spacing between categories in product listing
<script>
window.ec = window.ec || Object();
window.ec.storefront = window.ec.storefront || Object();
window.ec.storefront.product_list_category_cell_spacing = 20; // set custom spacing between categories in product listing in pixels
</script>
Set your custom spacing between categories in product listing (category pages) in pixels. If applied, categories will become smaller to allow for the set spacing.
Possible values: integer numbers. Default: not set.
If you apply the change after storefront has loaded, you can update its look on the fly using the Ecwid.refreshConfig()
function.
Set spacing between products in product listing
<script>
window.ec = window.ec || Object();
window.ec.storefront = window.ec.storefront || Object();
window.ec.storefront.product_list_cell_spacing = 20; // set custom spacing between categories in product listing in pixels
</script>
Set your custom spacing between products in product listing (category pages) in pixels. If applied, products will become smaller to allow for the set spacing.
Possible values: integer numbers. Default: not set.
If you apply the change after storefront has loaded, you can update its look on the fly using the Ecwid.refreshConfig()
function.
Control display mode of category names in product listing
<script>
window.ec = window.ec || Object();
window.ec.storefront = window.ec.storefront || Object();
window.ec.storefront.product_list_category_title_behavior = "HIDE"; // hide category name in product listing
</script>
Control the way category names are displayed in product listing (category pages).
Possible values: "SHOW_ON_IMAGE"
– default, "SHOW_BELOW_IMAGE"
, "HIDE"
, "SHOW_ON_HOVER"
.
If you apply the change after storefront has loaded, you can update its look on the fly using the Ecwid.refreshConfig()
function.
Change storefront labels
Format example
<script type="text/javascript">
ecwidMessages = {
"LABEL_NAME":"LABEL_VALUE",
"LABEL_NAME-2":"LABEL_VALUE-2",
"OTHER_LABEL_NAME":"OTHER_LABEL_VALUE"
};
</script>
Every text in Ecwid (that is not added by a merchant) is a label. You can change these labels yourself to translate your storefront or to make the wording more fitting a merchant’s individual Ecwid setup.
This translation includes adding of a special JavaScript code with the updated labels before the Ecwid integration code.
Replace “Shopping Bag” with “Shopping Cart”
<script type="text/javascript">
ecwidMessages = {
"BreadCrumbs.your_bag" : "Your shopping cart",
"Minicart.shopping_bag" : "Shopping Cart",
"ShoppingCartView.shopping_bag" : "Your Shopping Cart",
"EmptyShoppingCartPanel.empty" : "Your Shopping Cart is empty"
};
</script>
The format of this code is presented on the right. LABEL_NAME
is the internal name of the text label. LABEL_VALUE
is the text that is shown in the storefront.
For example:
to replace the “Shopping Bag” text with “Shopping Cart” in the bag widget and “your bag” page, we need to add the following code before this line:
<script type='text/javascript' src='http://app.ecwid.com/script.js?store_id'></script>
on your web page. See the example one the right!
Important notes:
- each line must be ended with comma except the last line
- do not leave empty lines in the Javascript code
- the special chars should be escaped. For example if the value of a label has double quote(“) it should be escaped with the slash(\”)
- some buttons are actually images, so you cannot translate them using JavaScript. Use CSS code to replace the images
- keep HTML tags in the label values, they’re necessary for correct Ecwid work
- mind the spaces after the label values. Some labels have it. So make sure that they won’t be loaded during the translation.
- UTF-8 charset is strongly recommended
- if you don’t like to insert many JavaScript lines to your store page, you can move them to the external JavaScript file: www.ecwid.com/forums/showthread.php?p=2337#15
If you’re not familiar with JavaScript, but want to translate a store or change its labels, you can use Storefront Label Editor or the Ecwid Translate Tool. It will make the translation much easier.
Change default colors and fonts
Change any color and main font for user’s storefront
Apply colors and fonts to storefront automatically from a website
Set storefront colors and font automatically
<script>
window.ec = window.ec || Object();
window.ec.config = window.ec.config || Object();
window.ec.config.chameleon = window.ec.config.chameleon || Object();
window.ec.config.chameleon.font = 'auto';
window.ec.config.chameleon.colors = 'auto';
</script>
Ecwid can automatically detect the main colors and fonts of a surrounding website and match the storefront automatically. To apply the colors and font automatically for a store, use the code on the right.
Set storefront colors
Set storefront colors automatically
<script>
window.ec = window.ec || Object();
window.ec.config = window.ec.config || Object();
window.ec.config.chameleon = window.ec.config.chameleon || Object();
window.ec.config.chameleon.colors = 'auto';
</script>
Set storefront colors manually
<script>
window.ec = window.ec || Object();
window.ec.config = window.ec.config || Object();
window.ec.config.chameleon = window.ec.config.chameleon || Object();
window.ec.config.chameleon.colors = {
'color-background':'#D3D3D3',
'color-foreground':'#4EA3F0',
'color-link':'#FF0606',
'color-button':'#4EA3F0',
'color-price':'#FF0606'
}
</script>
Set storefront colors and font example
<script>
window.ec = window.ec || Object();
window.ec.config = window.ec.config || Object();
window.ec.config.chameleon = window.ec.config.chameleon || Object();
window.ec.config.chameleon = {
colors: {
'color-button':'#4EA3F0',
'color-price':'#FF0606'
},
font: {
'font-family': 'arial,sans-serif'
}
}
</script>
Using the global Ecwid config object window.ec.config
you can control the colors in user’s storefront. To pre-define colors for a storefront, add JavaScript code on the right in the same frame, where Ecwid integration code is added.
auto
value allows Ecwid to detect the website colors around Ecwid storefront to adapt its colors automatically. Use the fields below to set colors manually.
Fields:
Name | Type | Description |
---|---|---|
color-background | string (HEX and RGBA color) | Background color for storefront and small buttons (“Clear bag”, “Apply”, etc.) |
color-foreground | string (HEX and RGBA color) | Color of all texts in storefront |
color-link | string (HEX and RGBA color) | Color for links in storefront (breadcrumbs, “Sign In”, “Favourites”, etc.) |
color-button | string (HEX and RGBA color) | Color for main buttons in storefront (“Add to bag”, “Checkout”, etc.) and small buttons on mouse hover (“Clear bag”, “Apply”, etc.) |
color-price | string (HEX and RGBA color) | Color for product prices in storefront |
Set storefront font
Set storefront font automatically
<script>
window.ec = window.ec || Object();
window.ec.config = window.ec.config || Object();
window.ec.config.chameleon = window.ec.config.chameleon || Object();
window.ec.config.chameleon.font = 'auto';
</script>
Set storefront font manually
<script>
window.ec = window.ec || Object();
window.ec.config = window.ec.config || Object();
window.ec.config.chameleon = window.ec.config.chameleon || Object();
window.ec.config.chameleon.font = {
'font-family': 'arial,sans-serif'
}
</script>
Set storefront colors and font example
<script>
window.ec = window.ec || Object();
window.ec.config = window.ec.config || Object();
window.ec.config.chameleon = window.ec.config.chameleon || Object();
window.ec.config.chameleon = {
colors: 'auto',
font: {
'font-family': 'arial,sans-serif'
}
}
</script>
Using the global Ecwid config object window.ec.config
you can control the fonts of all texts displayed in user’s storefront. To pre-define a font for a storefront, add JavaScript code on the right in the same fram, where Ecwid integration code is added.
auto
value allows Ecwid to detect the website’s main font to adapt its font automatically. You can also set a specific font-family for a storefront manually.
Custom themes
Example of custom CSS to modify storefront
/*
* Change Ecwid buttons style
*/
button.gwt-Button, #wrapper button.gwt-Button {
border-radius: 13px;
-moz-border-radius: 13px;
-webkit-border-radius: 13px;
height: 28px;
background-color: #e4e4e4;
padding: 0 15px;
}
button.gwt-Button:active,
#wrapper button.gwt-Button:active {
background-color: #999999;
}
div.ecwid-productBrowser-details-rightPanel div.ecwid-productBrowser-backgroundedPanel {
min-width:185px;
width:auto;
}
Add custom CSS theme in Ecwid Control Panel (for a single store)
Ecwid provides a merchant with a built-in CSS customization tool in their control panel in the 'Design’ section: Ecwid automatically loads the CSS code entered by user in their storefront. This allows merchants to customize their store look and feel flexibly. See also “How to change Ecwid design” article in our knowledge base.
Add custom CSS theme in an app (for multiple stores at once)
Ecwid API allows you to do the same in more convenient way: you simply specify the URL of file with your custom CSS code and Ecwid automatically loads that code in the user storefront. So you don’t need to put the CSS on user site manually or ask a merchant to do that.
In more details:
- After your app is registered, contact us and provide the https URL of the
.css
and file you’d like to load in the user storefront. - When asking a user to install your app, Ecwid will request the
customize_storefront
permission from them. (If your app is for a specific store, make sure to addcustomize_storefront
scope in the OAuth process.) - The next time merchant’s storefront is loaded in any browser or website, your external CSS file will be automatically appended, loaded, and executed on that page.
Q: Can I create new themes as apps?
Yes, you can! Please check out this page for more details: How to create a theme
Store-specific custom CSS
You may want to apply different CSS codes depending on the store your application is loaded.
For example, if your application provides new design themes for merchant storefront, you may need to give a merchant ability to choose the theme they want to enable and change the applied CSS code according to their choice.
In such cases, you will need to use custom JS files to dynamically detect merchant store ID and load different styles depending on the user store ID. See Custom JavaScript files for details.
Storefront interface translations
When the app adds new features to storefront that need translations, most likely the app loads its external JavaScript code too.
The app can determine the current language of storefront using the JS API method: Ecwid.getStorefrontLang
To translate the app in storefront, use these steps:
1/ Determine storefront language before initializing the app 2. Set/load the required translated text labels for app interface
If the current language is not supported, use the fallback labels. For example, load English texts if user is Spanish and you don’t have Spanish translations yet.