💡 Always initiate theme integration on a preview (duplicate) theme. Please don't integrate the app directly into your live theme.
Sparq's theme integration automates the process of incorporating search and filter functionality into Shopify themes. It adds necessary files, including snippets and assets, ensuring seamless integration while allowing for customization and optimal performance.
The instructions below are for theme version V9 or above. All integrations done after 1 Jun 2024, have theme version V9 or above. If you are unsure about your theme version, please reach out to support.
Automatic Theme Integration
The Themes page in Sparq allows for seamless integration of Sparq's search & filter app into your Shopify theme. This process is designed to be entirely automated, integrating all necessary assets for theme setup without requiring manual intervention.
To begin the integration process:
1. Navigate to the Themes section in your Sparq dashboard. You can find this by clicking on "Themes" in the left-hand menu, as shown in the image below,
2. You'll see a list of your Shopify themes displayed in a table format. The table includes columns for Theme Name, Last Updated, Preview, and Status.
3. For each theme, you have the option to:
- Preview the theme by clicking on "Preview Theme"
- Edit the theme code by clicking on "Edit Code"
- Start the integration process
4. To initiate the integration, locate the theme you want to integrate with Sparq and click the "Start Integration" button on the right side of the row.
5. Once the integration process is complete, the status for that theme will change to "Completed," and the "Start Integration" button will be replaced with a checkmark icon (as shown in Image 2 for the "Dawn - V9" theme).
6. If a theme is currently live in your store, it will be marked with a green "LIVE" tag next to its name.
It's important to note that while the integration process is automated, Sparq provides support if you encounter any issues. Contact our customer care via the in-app chat icon at the bottom right, or email [email protected].
This automatic integration ensures that all Sparq assets are properly incorporated into your Shopify theme, allowing for a smooth implementation of your store's search & filter functionality.
File Structure
When the Sparq integration is complete, several new files are added to your Shopify theme. These files are organized into two main sections: Snippets and Assets. Here's an explanation of each file:
Snippets
1. sq-assets-preload.liquid
This snippet preloads essential Sparq assets, improving the initial load time of your store. It ensures critical resources are fetched as early as possible in the page load process.
2. sq-assets.liquid
Contains the main Sparq assets required for the app to function. This snippet loads the core JavaScript and CSS files needed for Sparq's features.
3. sq-dropdown.liquid
Implements the dropdown functionality for Sparq's filter and search features. This snippet handles the creation and behavior of dropdown menus in the interface.
4. sq-filter-and-search.liquid
The primary snippet for Sparq's filter and search functionality. It renders the main interface components for searching and filtering products in your store.
5. sq-product.liquid
Handles the display and functionality of individual product items within Sparq's search and filter results. It ensures proper rendering of product information.
Assets
1. sq-app.min.css
The minified CSS file contains all styles specific to Sparq's interface elements. It ensures consistent and appealing styling across all Sparq components.
2. sq-app.min.js
The main minified JavaScript file for Sparq. It contains the core logic and functionality for the search and filter features.
3. sq-common.min.js
A minified JavaScript file with common utilities and functions used across various Sparq features. It helps reduce code duplication and improves maintainability.
4. sq-config.min.js
Contains configuration settings for Sparq. This file allows for customization of Sparq's behavior without modifying the core application code.
5. sq-custom.css
An empty CSS file is provided for store owners to add custom styles specific to their Sparq integration without modifying the core CSS files.
6. sq-custom.js
An empty JavaScript file where store owners can add custom scripts or modifications to Sparq's functionality.
7. sq-theme.css
Contains theme-specific styles for Sparq, ensuring that the app's interface blends seamlessly with your store's design.
8. sq-theme.js
Includes theme-specific JavaScript code to handle any necessary adjustments or customizations for proper integration with your store's theme.
This structure ensures a clean separation of concerns, making it easier to manage and customize the Sparq integration within your Shopify theme.
Customization
Sparq offers extensive customization options to ensure that the search and filter functionality seamlessly integrates with your Shopify store's unique design and requirements. This section will guide you through customizing two key files: sq-product.liquid and sq-filter-and-search.liquid.
Understanding the Code Structure
Before diving into customizations, it's crucial to understand the structure of these files:
1. Hybrid Code: The files use a combination of Liquid syntax and JavaScript (particularly Vue.js directives). This hybrid approach allows for dynamic rendering of product data while maintaining compatibility with Shopify's theming system.
2. Product Data Structure: Product data is referenced as `item` within the code. Its JSON structure mirrors the Shopify product JSON structure, as documented in the Shopify Admin API reference.
3. Displaying Product Data: To display product data, use double curly braces within Liquid raw tags:
{% raw %} {{ item.title }} {% endraw %}
4. Vue.js Directives: The templates use Vue.js directives for dynamic rendering. Always maintain these to ensure proper functionality.
Customizing sq-product.liquid
This file controls the appearance of individual product cards in the search and filter results.
Common customizations:
Adjusting the product card layout
Modifying the display of product information
Adding or removing elements like sale badges or stock status
Example customizations:
a) Changing the "Sale" label:
<div class="discount-label" v-if="item.compare_at_price && item.price && item.compare_at_price > item.price">
Special Offer
</div>
b) Adding a "New Arrival" badge:
<div class="new-arrival-label" v-if="item.published_at > recentDate">
New Arrival
</div>
c) Customizing the product title and adding vendor information:
<div class="sparq-product-title">
<a :href="'/products/' + item.handle" class="sparq-title h4 custom-font">
{% raw %} {{ item.title }} {% endraw %}
</a>
<div class="sparq-product-vendor">
{% raw %} {{ item.vendor }} {% endraw %}
</div>
</div>
Customizing sq-filter-and-search.liquid
This file controls the overall layout and functionality of the search and filter interface.
Common customizations:
Adjusting the filter layout
Modifying the sort options
Changing the appearance of the mobile filter toggle
Example customizations:
a) Changing the "Filter by" text:
<div class="sq-desktop-filter-header-title">Refine Results</div>
b) Modifying the clear all button:
<sq-clear>
<div class="sq-clear-btn custom-clear-btn">Reset Filters</div>
</sq-clear>
c) Customizing the mobile filter toggle icon:
```liquid
<span class="mobile-facets__open" onclick="toggleFilter()">
<i class="fas fa-sliders-h"></i>
<span class="mobile-facets__open-label button-label medium-hide large-up-hide">Filter and Sort</span>
</span>
Best Practices
1. Back up Original Files: Always create a backup of the original files before making any changes.
2. Maintain Core Structure: While customizing, ensure you maintain the core structure and functionality of Sparq.
3. Test Thoroughly: After making changes, test your customizations across various devices and screen sizes.
4. Use Existing Styles: Whenever possible, use your store's existing CSS classes and styles for consistency.
5. Careful with New Functionality: If adding new features, ensure they don't conflict with Sparq's core functionality.
6. Proper Syntax Usage:
- Use item to access product properties (e.g., item.title, item.price, item.images).
- Utilize Vue.js directives for dynamic rendering (e.g., v-if, v-for).
- Always wrap Vue.js expressions in {% raw %} {% endraw %} tags to prevent Liquid processing conflicts.
- You can use both Liquid filters (like `| money`) and JavaScript methods to manipulate data as needed.
7. Consult Support: If you're unsure about a particular modification, don't hesitate to contact Sparq's support team or consult a developer familiar with the integration.
By following these guidelines and understanding the hybrid nature of the code, you can effectively customize your Sparq integration to align perfectly with your store's design and functionality requirements. Remember, the goal is to enhance the user experience while maintaining the powerful search and filter capabilities that Sparq provides.
Themes Supported
Sparq is designed to enhance your Shopify store's search and filter functionality while seamlessly integrating with your chosen theme. We offer various options to ensure that Sparq works beautifully with your store's design, regardless of the theme you're using.
Themes Supported Out of the Box
We offer optimized, out-of-the-box support for several popular Shopify themes. These pre-configured integrations ensure a smooth setup process and optimal performance with minimal customization required. The themes we currently support out of the box are:
1. Dawn
Shopify's default theme, known for its clean, modern design and excellent performance.
2. Colorblock
A vibrant and customizable theme that allows for bold color choices and striking product displays.
3. Impulse
A versatile theme designed to showcase products effectively across various industries.
4. Sense
A sleek, minimalist theme that puts your products front and center.
5. Craft
An artisanal theme perfect for handmade goods and craft stores.
For these supported themes, you can expect:
Automatic style matching to ensure Sparq elements blend seamlessly with your theme's design.
Pre-configured layouts optimized for each theme's unique structure.
Tested compatibility to minimize potential conflicts.
Faster integration process with reduced need for custom code.
If you're using one of these themes, you can be confident that Sparq will integrate smoothly with your store's design right from the start.
Themes Not Supported Out of the Box
While we offer optimized support for several popular Shopify themes, we understand that you may be using a different theme or have specific design requirements. For these cases, we have you covered:
Default High-Converting Theme
For stores using themes not listed in our out-of-the-box support, Sparq provides an excellent, high-converting default theme. This theme is:
Designed for optimal user experience
Optimized for conversion rates
Mobile-responsive
Easy to integrate with your existing store design
Our default theme ensures that you can immediately benefit from Sparq's powerful search and filter functionality without worrying about compatibility issues or extensive customization.
Custom Theme Integration
We believe that your search and filter experience should seamlessly blend with your store's unique design. That's why we offer custom theme integration services at no additional cost. If you would like to customize the Sparq interface to match your specific theme:
Reach out to our support team
Provide details about your current theme and desired customizations
Our experts will work with you to tailor Sparq's appearance to your exact specifications
This service includes:
Custom CSS modifications
Layout adjustments to match your theme's structure
Integration of your brand colors and typography
Ensuring responsiveness across all devices
By offering this service, we ensure that every store owner can achieve a perfectly integrated search and filter experience, regardless of their chosen theme.
To get started with custom theme integration, simply contact our support team with your requirements. We're committed to helping you create the best possible shopping experience for your customers, aligned perfectly with your brand and design preferences.
Troubleshooting
While Sparq is designed for seamless integration with your Shopify theme, you may occasionally encounter issues. This troubleshooting guide will help you address common problems and ensure your Sparq search and filter functionality works smoothly.
1. Sparq Features Not Appearing
If Sparq's search and filter features are not visible on your store:
Ensure the integration process completed successfully.
Check if the Sparq app is installed and active in your Shopify admin.
Verify that the necessary Sparq snippets are present in your theme files.
Clear your browser cache and refresh the page.
2. Styling Inconsistencies
If Sparq elements don't match your theme's style:
Review your custom CSS in
sq-custom.css.Check for conflicts between Sparq's styles and your theme's CSS.
Ensure you're using the correct class names when customizing Sparq elements.
3. Product Data Not Displaying Correctly
If product information is missing or incorrect:
Verify that you're using the correct item properties (e.g.,
item.title,item.price).Check if the data is available in your Shopify product JSON.
Ensure Vue.js expressions are wrapped in Liquid raw tags: `{% raw %} {{ item.property }} {% endraw %}`.
4. Filter or Search Not Working as Expected
If filters or search functionality isn't behaving correctly:
Check the browser console for any JavaScript errors.
Verify that you haven't accidentally removed or modified crucial Vue.js directives.
Ensure your customizations haven't interfered with Sparq's core functionality.
5. Performance Issues
If your store is experiencing slow load times after integrating Sparq:
Minimize custom JavaScript and CSS.
Ensure you're not loading unnecessary assets.
Check if your theme has conflicting JavaScript that might be interfering with Sparq.
6. Mobile Responsiveness Problems
If Sparq doesn't display correctly on mobile devices:
Test on various devices and browsers.
Review your custom CSS for any non-responsive styles.
Ensure you haven't removed any of Sparq's responsive classes or elements.
7. Updates Not Reflecting
If your changes to Sparq files are not reflecting on your live site:
Make sure you've saved all changes.
Clear your browser cache and refresh the page.
Check if your theme needs to be republished in Shopify.
8. Conflict with Other Apps
If Sparq conflicts with other Shopify apps:
Temporarily disable other search or filter apps to isolate the issue.
Check for JavaScript conflicts in the browser console.
Ensure other apps are not overriding Sparq's functionality.
General Troubleshooting Steps:
Review recent changes: If the issue started after a recent update or customization, review those changes.
Check browser console: Look for any error messages that might provide clues about the problem.
Revert to default: Temporarily revert to Sparq's default settings to see if the issue persists.
Test in incognito mode: This can help determine if the issue is related to browser extensions or cached data.
Verify Shopify theme: Ensure your Shopify theme is up to date and compatible with the latest version of Sparq.
If you've gone through these troubleshooting steps and are still experiencing issues, don't hesitate to contact Sparq support. Provide them with:
A detailed description of the problem
Steps to reproduce the issue
Screenshots or screen recordings if applicable
Your Shopify store URL
Any recent changes made to your theme or Sparq integration
By following these troubleshooting steps, you should be able to resolve most common issues with your Sparq integration.
Remember, Sparq's support team is always available to assist you with more complex problems.