Skip to main content

Snippets

This technical reference provides an in-depth look at the implementation of core storefront components for the Soppiya Innovation Ltd SaaS platform. It covers the logic for global layouts, dynamic styling, and interactive UI modules using Liquid, CSS, and the Soppiya AJAX API.

Global Layout Engine (theme.liquid)​

The theme.liquid file acts as the primary orchestrator for the storefront. It initializes the environment, manages global assets, and defines the design system via CSS variables.

Key Logic:​

  • Language Localization: The lang attribute is dynamically set using {{ request.locale.iso_code }} to ensure SEO and accessibility compliance.
  • Asset Management: Uses asset_url combined with stylesheet_tag or script_tag to serve files via the Soppiya CDN.
  • Modular Rendering: Implements <header-group> and <footer-group> using the {% sections %} tag to allow multi-section management.
important

Platform Requirements: Every layout file must include {{ content_for_header }} in the <head> and {{ content_for_layout }} in the <body> to allow system script injection and template rendering.

Dynamic Design System (CSS Variables)​

Soppiya themes utilize a data-driven design system where visual attributes are pulled directly from settings.json and mapped to CSS :root variables.

Color Scheme Implementation​

The platform supports multiple color schemes. The following logic iterates through available schemes to apply the merchant’s selected theme color:

:root {
  {% for scheme in settings.color_schemes %}
    {% if settings.theme_color_scheme == scheme[0] %}
      --primary_color: {{ scheme[1].settings.primary_color }};
      --text_color: {{ scheme[1].settings.text_color }};
      /* ... other mappings ... */
    {% endif %}
  {% endfor %}
}
tip

Component Isolation: Use the --{{id}}_variable pattern within sections to allow specific components to overwrite global styles if the merchant enables "Overwrite Color Scheme" in the editor.

Product UI & Interaction Logic​

The product system is built to handle complex variant structures and real-time inventory feedback.

Variant & SKU Management​

The theme uses a matchedVariants logic in JavaScript to detect user selections from radio inputs and update the DOM (Price, SKU, and Images) instantly without page reloads.

AJAX Add-to-Cart​

Soppiya provides a native add_cart_item() function. Developers should implement state-based buttons (Loading → Success/Error) to provide visual confirmation.

try {
  await add_cart_item({ variant, quantity: min });
  this.classList.add("sp_btn_success"); // Success feedback
} catch (error) {
  this.classList.add("sp_btn_error"); // Error feedback
}
warning

Stock Enforcement: Always check product.variants[0].available and sell_when_out_of_stock logic. If a product is unavailable and "overselling" is disabled, the button must transition to a btn_disabled state.

Navigation & Global Accessors​

Soppiya simplifies data retrieval through Global Accessors (underscore prefix), allowing menus and resources to be called from any template.

Desktop & Mobile Menus​

  • Data Source: _linklist['main-menu'] and _linklist['mobile-menu'].
  • Logic: Nested menus are handled via a link.links.size check. If sub-links exist, the UI renders a <div class="sp_sub_menu_wrapper"> or a mobile drawer.
note

Active State Persistence: The navigation uses localStorage to remember the activeMenuIndex. This ensures that if a user clicks a menu item and the page reloads, the "active" highlight remains on the correct link.

Search & Discovery​

Predictive Search Popup​

Soppiya utilizes an asynchronous predictiveSearch() function to fetch results as the user types.

  • Results Handling: Returns an array of products and collections.
  • UI Pattern: If no results are found, a "No products found" message is injected into the sp_predictive_search_results container.

Search Results Page​

The search.json template loops through the results object. It uses the truncate filter to keep excerpts consistent and the render tag to display the standardized product-card.

Content Marketing (Blogs & Articles)​

Articles are rendered using a standardized card pattern to maintain visual harmony across the site.

  • Date Formatting: Use the date filter (e.g., {{ article.createdAt | date: "%a, %b %d, %y" }}) for localized timestamps.
  • Visual Assets: The article.thumbnail is the primary image source for grid views.

Customer Engagement Tools​

Social Contact Plugin​

A fixed-position toggle (.social-container) allows customers to reach merchants via WhatsApp or Messenger.

  • Merchant Configuration: Links are pulled dynamically: https://wa.me/{{ settings.chat_whatsapp_number }}.
  • Animations: The plugin uses CSS @keyframes scaleIcon to create a "pulsing" effect, increasing visibility and engagement.

Technical Best Practices​

  1. Lazy Loading: Always include loading="lazy" on non-hero images to improve initial page load performance.
  2. API Fallbacks: When calling Soppiya API functions (like add_cart_item), wrap them in try...catch blocks to prevent console errors from stopping other site scripts.
  3. JSON Serialization: Use the | json filter when passing Liquid data to JavaScript variables to ensure proper data escaping and formatting.

For further integration details regarding checkout processing, proceed to the Checkout API Documentation.