Ecwid Developers API Documentation

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 the grid(3,3) or list(10) or table(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 view
list(M) - M is a number of products on one page in list view
table(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%"

"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.

<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