WooCommerce

The theme's shop code lives in inc/WooCommerce and runs only when WooCommerce is active. It keeps WooCommerce's own layout CSS (with its RTL files) and adds woocommerce.css (src/scss/woocommerce), built on the theme's color, radius and button tokens. No template files are overridden, so WooCommerce updates never make theme templates outdated.

Store base

• Wrappers and layout (WooCommerce): shop pages use the theme's content area. The shop and product categories get the Shop sidebar widget area, placed by Theme Options → Shop → Catalog → Sidebar (and hidden when it has no widgets). Product, cart, checkout and account pages are full width. The title bar carries the title ("Shop", the category) and the breadcrumbs.
• Catalog (Catalog): products per page; columns per device (a CSS grid fed by --bt-shop-cols); grid or list layout; card look (default, card, minimal, overlay); image shape; hover zoom; add to cart always or on hover; which parts a card shows; sale badge as "Sale!" or the discount percent, in four shapes; a "New" badge for products from the last N days.
• Catalog mode: nothing can be bought, prices can be hidden, and product pages can show an inquiry button. In its link, {product} becomes the product name, for example mailto:shop@example.com?subject={product}.
• Product page (Product): layout (default, wide gallery, sticky summary, stacked), thumbnails below or beside the image or hidden, gallery zoom and lightbox. Details show as tabs, an accordion (first panel open) or open sections. SKU, categories, tags, share buttons, related products (count and columns) and upsells can each be turned off. A Single product template replaces this layout where it matches.
• Cart and checkout (CartCheckout): one column or two (items beside the totals, details beside the order). The distraction free checkout replaces the header with the logo, "Secure checkout" and "Back to cart", and the footer with the copyright. It does this through the bluetheme_location_override filter, so it works with both the classic and the block checkout.
• Currency label (Localization): for IRR and IRT, the symbol reads Toman or Rial as chosen in Theme Options → Global → Localization. Prices use Persian digits on Persian sites (the wc_price filter is part of Persian digits).
• Iranian addresses: province, city, address, then postal code (required). Off while Persian WooCommerce is active.
• Province → city lists (IranCities, src/frontend/iran-cities.js): with Iran and a province chosen, the city field becomes a searchable list of 2,704 cities. The city is still sent as text, so orders and shipping plugins work as usual. The data (inc/WooCommerce/data/iran-cities.php) is generated by tools/build-iran-cities.mjs from Persian WooCommerce's list (GPL-2.0-or-later), without entries that are not places, and keeps the Iran Post city codes. The lists are off while Persian WooCommerce is active (it has its own).
  • They work on the classic checkout and the account address forms ([woocommerce_checkout]). WooCommerce's block checkout renders its fields itself, so it keeps a text field there. Most Iranian payment gateways need the classic checkout anyway.

Shopping features

All of these are in Theme Options → Shop and use one script, shop.js (src/frontend/shop), configured through window.btShop (the bluetheme_shop_script filter). Styles are in src/scss/woocommerce/_extras.scss.

• Side cart (Cart): the header cart icon opens a side panel with the mini cart instead of going to the cart page (Side cart drawer). It can open by itself after a product is added (Open the side cart after adding a product). Cart counts in the header (classic header and the Cart element) update without a reload through WooCommerce's cart fragments.
• AJAX add to cart on product pages (Add to cart without reloading on product pages): simple and variable products are added without leaving the page. Errors (out of stock, a missing option) show above the form. Grouped products, and stores set to go to the cart after adding, keep the normal submit.
• Load more and infinite scroll (Pagination: numbers, load more, infinite): the next page's products are added to the list. The blog's load more code handles both (data-list names the list), and the bt:items-added event lets the shop features set up the new cards.
• Filters on small screens (Filters in a slide-out panel on mobile): below 992px the Shop sidebar becomes a side panel opened by a "Filters" button above the products.
• Hover image (Image hover): a card shows the product's first gallery image on hover.
• Card buttons: quick view and wishlist buttons over the card image, shown on hover (always on touch screens), each one picked in Show on cards. Add your own through the bluetheme_card_actions filter.
• Quick view (QuickView, Quick view): a dialog with the gallery, price, short description and the add to cart form (variations and swatches work). The markup comes from GET bluetheme/v1/quick-view/{id} (public; published, visible products only).
• Wishlist (Wishlist, Wishlist: built-in, YITH, off):
  • Built-in: heart buttons on cards and product pages. Visitors' lists stay in their browser (localStorage). Signed-in customers' lists are saved to their account, and a browser list is merged in when they sign in.
  • Choose the Wishlist page, or put [bluetheme_wishlist] on any page. The header heart (classic header and the Wishlist element) links there and shows the count.
  • YITH: with YITH WooCommerce Wishlist active, the buttons and the header link use YITH's.
• Swatches (Swatches, Variation swatches): variation dropdowns become buttons (labels, color dots or images, round or square, in the chosen size). Colors and images are set on the terms of global attributes (Products → Attributes → a term: Swatch color, Swatch image). Values without one, and attributes made on the product itself, show labels. The dropdown stays in the form, hidden, so WooCommerce's variation logic works as usual.
• Sticky add to cart (StickyCart, Sticky add-to-cart bar: off, phones, all screens): once the form scrolls out of view, a bar with the image, name, price and button sticks to the bottom. For simple products the button submits the form; for others it scrolls back to the options.
• Persian digits now also cover markup loaded after the page: cart fragments, quick view and the wishlist page. REST routes that return page markup turn on the bluetheme_visitor_output filter.

Theme hooks added for this batch: bluetheme_sidebar_classes (sidebar classes) and the bluetheme_sidebar_start action (before the widgets), bluetheme_wishlist_url.

Builder shop elements and templates

All shop elements have "needs": "woocommerce" in config.json, so they are hidden from the builder while WooCommerce is off. Shared code is in ElementParts.

WooCommerce elements (category "WooCommerce"; Shop Slider is under "Sliders"):

• Shop: a product grid of the latest, featured, on sale, best selling, top rated or chosen products. It can be limited to categories, sorted, given columns per device and page numbers. It is built on WooCommerce's [products] shortcode class, so hidden and out-of-stock rules and the shop's cards (quick view, wishlist, hover image) apply.
• Shop Slider: the same products as Swiper slides, with the Blog Slider's slider settings.
• Product Categories: category cards (image above the name, name over the image, or a round image) with product counts. With no categories ticked it shows the top-level ones, without "Uncategorized".
• Mini Cart: the cart items, subtotal and buttons in place, for sidebars, panels and mega menus. It updates with the cart (it uses WooCommerce's .widget_shopping_cart_content box).
• Shop Products: the products of the shop page, category or tag being viewed (the main query), with WooCommerce's notices, result count, sorting, pagination (numbers, load more or infinite, per Theme Options) and a Filters button. Each part can be turned off.

Product page elements (category "Product page"): Product Title, Product Gallery, Product Price, Product Add to Cart, Product Rating, Product Short Description, Product Description, Product Additional Information, Product Meta, Product Tabs (tabs, accordion or open sections), Product Reviews, Related Products and Product Upsells. Breadcrumbs is the theme's Breadcrumbs element, which already shows Shop → category → product. Each reads the product being viewed and shows a builder hint when it has nothing to show (no reviews, no upsells…). Product Add to Cart keeps swatches, the wishlist button and AJAX add to cart; in catalog mode it shows the inquiry button.

Templates (Templates, inc/Templates/Dynamic.php):

• A Single product template replaces the product page layout on the products its conditions match. The template is printed inside the product's own div#product-ID.product, after the shop notices. WooCommerce's product structured data is still printed.
• A Shop archive template replaces the shop page and product category and tag archives.
• Starters: a Single product template starts as the gallery beside a sticky summary (breadcrumbs, title, rating, price, short description, add to cart, meta, share), then tabs, upsells and related products. A Shop archive template starts as a title bar, then the Shop sidebar (as a filter panel on phones) beside the products.
• In the builder: the template previews with a product (the "Preview with" setting, or the latest), or with the latest products. WooCommerce's gallery, zoom, lightbox and variation scripts load on the canvas. Product Gallery's script.js sets the gallery, variation forms and tabs up again whenever the canvas renders a section again. Product Add to Cart, Product Tabs and Product Reviews reuse it through uses.
• Filters on phones: the Sidebar element has a new "Slide-out panel on phones and tablets" switch, and the Filters button of Shop Products opens it. Without such a panel on the page the button is hidden. The theme sidebar's own panel is not used under a template.

Changes elsewhere:

• Archive titles: the shop and category archive titles read "Shop" or the category name (the get_the_archive_title filter), not "Archives: Products".
• Add to cart on product pages: the cart is now read from the page the form was sent to, not from a second request. WooCommerce saves the cart only after it sends that page, so a new visitor's first item could be missing from the count and the side cart.
• Product layout option: the "Builder template" choice is gone from Theme Options → Shop → Product page → Layout. A matching Single product template replaces whichever layout is chosen.

One-time code login

See account.md.

Other details:

• Disabled main buttons (.button.alt) keep the theme color instead of WooCommerce's purple.
• Theme Options → Translate has a "Shop" group with the shop's texts.

Development

pnpm env:plugins downloads WooCommerce, Persian WooCommerce and the ZarinPal gateway (the stable versions) into .wp-env-plugins/, which .wp-env.json maps in.

• The Persian site (:8888) runs all three and sells in Toman.
• The English site (:8889) runs WooCommerce alone, so the theme's own city lists can be tested there.
• tools/wp-env/shop-sample.php adds two categories and seven products (simple, on sale, out of stock, variable) once per site.