GraphQL

Efficiently Extract Object References in Shopify Storefront GraphQL API

William Mimura

Published Mar 29, 2024

Updated Apr 1, 2024

4 min read

Efficiently Extract Object References in Shopify Storefront GraphQL API

Introduction

So, this blog post is born out of necessity and a bit of frustration. If you're diving into the world of Shopify's Storefront API, you've probably realized that while it's powerful, extracting data in the object reference from Metadata fields or Metaobjects (in the GraphQL query) can be a bit like searching for a needle in a haystack. This complexity often arises not from the API's lack of capabilities but from the sparse and sometimes unclear documentation on this specific aspect.

That's precisely why I decided to create this post. As a developer, I found myself in a situation where the documentation and community resources were either scarce or not detailed enough for the specific challenges I faced. This guide is the result of my journey - from confusion to clarity.

The Situation

To understand the crux of my challenge, it's essential to recognize that creating metafields and metaobjects is a common practice for those seeking a more customized and controlled experience with Shopify CMS. In my specific case, I wanted to enrich the information available for each product's vendor beyond what Shopify typically allows, which is just a single text box. I aimed to have each vendor display their name and two versions of their logo: a themed logo that aligns with my website's color scheme and an original logo for use on specific pages.

The challenge emerged when I fetched a list of all vendors to display on a page. My GraphQL query for the Storefront API looked like this:

query vendorsMetaObjects($country: CountryCode, $language: LanguageCode)
@inContext(country: $country, language: $language) {
    vendorsCollection: metaobjects(type: "vendor", first: ${MAX_PAGE_BY}) {
        nodes {
            name: field(key: "name") {
                value
            }
            originalLogo: field(key: "original_logo") {
                value
            }
            themedLogo: field(key: "themed_logo") {
                value
            }
        }
    }
}

This was when I hit a roadblock. How do I fetch a field with a more complex type than a simple text or number, like an image? To retrieve the correct data, what specific details must I include in the originalLogo and themedLogo fields?

In my quest for a solution, I turned to every resource I could think of. I combed through the Storefront API documentation, searched endlessly on Stack Overflow, and browsed various tech forums. Despite all these efforts, I couldn’t find the clear, detailed answers I needed. It felt like I was looking for something that should be there but wasn’t.

Solution

Before diving into the solution, it's important to note that this is the method I discovered through trial and error. There might be other approaches, but I want to share the process that worked for me without clear documentation.

My first step was to understand the nature of the data returned by the Storefront API. I inspected the value of a metaobject, which looked something like this:

{
  "name": { "value": "A Vendor Test 1" },
  "originalLogo": { "value": "gid://shopify/MediaImage/some_ID" },
  "themedLogo": { "value": "gid://shopify/MediaImage/some_other_ID" }
}

The key here was the gid, or global unique identifier. What stood out was that it always includes the object type, in this case, MediaImage. This was crucial because it indicated which union to use and what properties to query from this object in the Storefront API documentation.

So, I modified my query to include a reference to this object type, focusing on the originalLogo field as an example:

query vendorsMetaObjects($country: CountryCode, $language: LanguageCode)
@inContext(country: $country, language: $language) {
    vendorsCollection: metaobjects(type: "vendor", first: ${MAX_PAGE_BY}) {
        nodes {
            # ...
            originalLogo: field(key: "original_logo") {
                value
                reference {
                    ... on MediaImage {
                        # Explore MediaImage documentation for extractable fields
                    }
                }
            }
            # ...
        }
    }
}

The next step was to consult the Storefront API documentation for MediaImage at Shopify API Documentation. Here, I discovered the image field within MediaImage, an object containing the url field. With this information, I updated my query:

query vendorsMetaObjects($country: CountryCode, $language: LanguageCode)
@inContext(country: $country, language: $language) {
    vendorsCollection: metaobjects(type: "vendor", first: ${MAX_PAGE_BY}) {
        nodes {
            name: field(key: "name") {
                value
            }
            originalLogo: field(key: "original_logo") {
                reference {
                    ... on MediaImage {
                        image {
                            url
                        }
                    }
                }
            }
            themedLogo: field(key: "themed_logo") {
                reference {
                    ... on MediaImage {
                        image {
                            url
                        }
                    }
                }
            }
        }
    }
}

Finally, when executing this query, the output for a single object was as follows:

{
  "name": { "value": "A Vendor Test 1" },
  "originalLogo": {
    "reference": {
      "image": {
        "url": "https://cdn.shopify.com/s/files/rest_of_the_url"
      }
    }
  },
  "themedLogo": {
    "reference": {
      "image": {
        "url": "https://cdn.shopify.com/s/files/rest_of_the_url"
      }
    }
  }
}

Through this process, I successfully extracted the necessary data from the object references in the metafields, specifically handling more complex data types like images.

Conclusion

In wrapping up, it's vital to emphasize that while this guide focused on extracting MediaImage data from Shopify's Storefront API, the methodology I've outlined is broadly applicable. The key is understanding the structure of the gid (global unique identifier) and using it to identify the correct object types within your GraphQL queries.

Whether you're dealing with images or any other data type defined in Shopify's Storefront API, this approach can be your compass. Dive into the API documentation, identify the object types relevant to your needs, and adapt your queries accordingly. It's a versatile strategy that can be tailored to suit many requirements.

Remember, the world of APIs and e-commerce is constantly evolving, and staying adaptable and resourceful is crucial. This journey has been a testament to the power of perseverance and creative problem-solving in the face of technical challenges. May your ventures into Shopify's Storefront API be equally rewarding and insightful.

This Dot is a consultancy dedicated to guiding companies through their modernization and digital transformation journeys. Specializing in replatforming, modernizing, and launching new initiatives, we stand out by taking true ownership of your engineering projects.

We love helping teams with projects that have missed their deadlines or helping keep your strategic digital initiatives on course. Check out our case studies and our clients that trust us with their engineering.

About the author(s)

William Mimura
@mimurawil

Setting Up a Shopify App: Retrieving Fulfillment IDs

This is Part 2 of an ongoing series showing developers how to set up and deploy their own Shopify App! Find Part 1 here. Today, we are going to continue our adventure! Last we left off, we made it through quite a bit, from setting up our Shopify App to retrieving customer orders. Though today's adventure will have us encounter retrieving fulfillment ids. This will be needed for our grand finale, which will be updating customer orders with tracking information. Now, if we have any new adventurers with us or you just need a recap of our last session, you can head over here. Alternatively, if you just want the code from last time that can be found here. If you want to skip ahead and look at the code, it can be found here. With that all said, let us start retrieving those fulfillment ids! We’re going start off by heading on over to our ` file, and making changes to the loader function. Here, we need to retrieve our session, which we’ll do by adding: ` between our const orders and before our return json, and it should look like this afterward. ` We’re going to need this to retrieve our fulfillment order information. With that, out of the way we’ll start by calling ` to retrieve our fulfillment orders. This will require the session we added and the order IDs from the orders we retrieved above in our previous blog post. Here is a rough look at what the call will be. ` We need to make a few changes though to get this up and running. First our order.id lives inside of an orders array so we’ll need to loop over this call. Second order.id also contains a bunch of unneeded information like `, so we’ll need to remove that in order to get the string of numbers we need. With those conditions outlined, we’ll go ahead and wrap it in a for loop, and use .replace to resolve the order.id issue, which gives us: ` Now that we are able to loop over our call and have gotten the order IDs properly sorted, we still have a couple of issues. We need a way to use this data. So we’re going to set a variable to store the call, and then we’ll need a place to store the fulfillment ID(s). To store the fulfillment ID(s), we’ll create an array called fulfillmentIds. ` For the call, we’ll label it as fulfillmentOrder. ` We should now have something that looks like this: ` We’re now almost there, and we just need to figure out how we want to get the fulfillment ID(s) out of the fulfillmentOrder. To do this, we’ll map over fulfillmentOrder and check for the open status, and push the IDs found into our fulfillmentIds array. ` Awesome! Now we have our fulfillment ID(s)! We can now return our fulfillment ID(s) in our return json() section, which should look like this. ` Our code should now look like this: ` We can now look at our terminal and see the fulfillmentIds array returning the fulfillment ID(s). Conclusion And there we have it! Part 2 is over and we can catch our breath. While it was a shorter adventure than the last one, a good chunk was still accomplished. We’re now set up with our fulfillment ID(s) to push on into the last part of the adventure, which will be updating customer orders with tracking information....

Aug 25, 2023

3 mins

Shopify

How to create and use custom GraphQL Scalars

How to create and use custom GraphQL Scalars In the realm of GraphQL, scalars form the bedrock of the type system, representing the most fundamental data types like strings, numbers, and booleans. As explored in our previous post, "Leveraging GraphQL Scalars to Enhance Your Schema," scalars play a pivotal role in defining how data is structured and validated. But what happens when the default scalars aren't quite enough? What happens when your application demands a data type as unique as its requirements? Enter the world of custom GraphQL scalars. These data types go beyond the conventional, offering the power and flexibility to tailor your schema to precisely match your application's unique needs. Whether handling complex data structures, enforcing specific data formats, or simply bringing clarity to your API, custom scalars open up a new realm of possibilities. In this post, we'll explore how to understand, create, and effectively utilize custom scalars in GraphQL. From conceptualization to implementation, we'll cover the essentials of extending your GraphQL toolkit, empowering you to transform abstract ideas into concrete, practical solutions. So, let's embark together on the journey of understanding and utilizing custom GraphQL scalars, enhancing and expanding the capabilities of your GraphQL schema. Understanding Custom Scalars Custom scalars in GraphQL extend beyond basic types like String or Int, allowing data to be defined, validated, and processed more precisely. They're instrumental when default types don't quite capture the complexity or specificity of the data, such as with specialized date formats or unique identifiers. The use of custom scalars brings several benefits: * Enhanced Clarity: They offer a clearer representation of what data looks like and how it behaves. * Built-in Validation: Data integrity is bolstered at the schema level. * Flexibility: They can be tailored to specific data handling needs, making your schema more adaptable and robust. With this understanding, we'll explore creating and integrating custom scalars into a GraphQL schema, turning theory into practice. Creating a Custom Scalar Defining a Custom Scalar in TypeScript: Creating a custom scalar in GraphQL with TypeScript involves defining its behavior through parsing, serialization, and validation functions. * Parsing: Transforms input data from the client into a server-understandable format. * Serializing: Converts server data back to a client-friendly format. * Validation: Ensures data adheres to the defined format or criteria. Example: A 'Color' Scalar in TypeScript The Color scalar will ensure that every color value adheres to a valid hexadecimal format, like #FFFFFF for white or #000000 for black: ` In this TypeScript implementation: * validateColors: a function that checks if the provided string matches the hexadecimal color format. * parseValue: a method function that converts the scalar’s value from the client into the server’s representation format - this method is called when a client provides the scalar as a variable. See parseValue docs for more information * serialize: a method function that converts the scalar’s server representation format to the client format, see serialize docs for more information * parseLiteral: similar to parseValue, this method function converts the scalar’s value from the client to the server’s representation format. Still, this method is called when the scalar is provided as a hard-coded argument (inline). See parseLiteral docs for more information In the upcoming section, we'll explore how to incorporate and validate these custom scalars within your schema, ensuring they function seamlessly in real-world scenarios. Integrating Custom Scalars into a Schema Incorporating the 'Color' Scalar After defining your custom Color scalar, the next crucial step is effectively integrating it into your GraphQL schema. This integration ensures that your GraphQL server recognizes and correctly utilizes the scalar. Step-by-Step Integration 1. Add the scalar to Type Definitions: Include the Color scalar in your GraphQL type definitions. This inclusion informs GraphQL about this new scalar type. 2. Resolver Mapping: Map your custom scalar type to its resolver. This connection is key for GraphQL to understand how to process this type during queries and mutations. ` 1. Use the scalar: Update your type to use the new custom scalar ` Testing the Integration With your custom Color scalar integrated, conducting thorough testing is vital. Ensure that your GraphQL server correctly handles the Color scalar, particularly in terms of accepting valid color formats and rejecting invalid ones. For demonstration purposes, I've adapted a creation mutation to include the primaryColor field. To keep this post focused and concise, I won't detail all the code changes here, but the following screenshots illustrate the successful implementation and error handling. Calling the mutation (createTechnology) successfully: Calling the mutation with forced fail (bad color hex): Conclusion The journey into the realm of custom GraphQL scalars reveals a world where data types are no longer confined to the basics. By creating and integrating scalars like the Color type, we unlock precision and specificity in our GraphQL schemas, which significantly enhance our applications' data handling capabilities. Custom scalars are more than just a technical addition; they testify to GraphQL's flexibility and power. They allow developers to express data meaningfully, ensuring that APIs are functional, intuitive, and robust. As we've seen, defining, integrating, and testing these scalars requires a blend of creativity and technical acumen. It encourages a deeper understanding of how data flows through your application and offers a chance to tailor that experience to your project's unique needs. So, as you embark on your GraphQL journey, consider the potential of custom scalars. Whether you're ensuring data integrity, enhancing API clarity, or simply making your schema a perfect fit for your application, the possibilities are as vast as they are exciting. Embrace the power of customization, and let your GraphQL schemas shine!...

Apr 10, 2024

5 mins

GraphQLJavaScript

Our Journey from Cypress to Playwright for E2E Testing

Our Journey from Cypress to Playwright for E2E Testing Introduction Adapting to unexpected technical challenges often leads to innovation. Our team faced such a moment when we discovered that our primary end-to-end (E2E) testing framework, Cypress, was incompatible with an essential component of our tech stack. This discovery led us to consider alternatives to resolve the compatibility issue and enhance our testing processes. Our choice was Playwright, a modern testing framework acclaimed for its robust features and compatibility with multiple browsers. The shift to Playwright was swift and efficient: all our E2E tests were successfully migrated within a few hours. This rapid transition highlighted our team's ability to adapt and integrate new technologies quickly. In this blog post, we will share the hands-on process we followed during the migration to Playwright, the challenges we encountered along the way, and the solutions we implemented to overcome them. Using a Test Conversion Tool We utilized a third-party test conversion tool to facilitate our migration from Cypress to Playwright, which significantly streamlined the process. Among several options available, we chose Ray's Cypress to Playwright Conversion Tool for its ease of use and effectiveness. This tool allowed us to automatically transpose our existing Cypress tests into the Playwright format. The tool processes each test script by identifying equivalent functions and commands in Playwright, translating our entire suite with minimal input. Below are some before and after images of our test scripts, demonstrating the tool's conversion capabilities. One test script written in Cypress: ` And its result converted in Playwright: ` While the tool performed impressively, converting most of our tests accurately had limitations. Certain custom helper functions and test aliases did not translate directly, and the tool clearly marked these for manual intervention. This feature was beneficial as it allowed us to quickly identify and address the segments that required our attention. Small Fixes and Fine-Tuning The initial output from the conversion tool was highly useful, yet it required some tweaks to align with Playwright's capabilities perfectly. The tool conveniently marked each unconverted function with the identifier FIXME_, making it straightforward to address these specific areas. Here’s how we tackled some of these functions: FIXME_visitWithTimeout: Originally a custom Cypress command designed to visit a URL with a specified timeout (cy.visit(url, { timeout: 30000 })), this was straightforwardly converted to Playwright's page.goto(url) FIXME_getDataCy: Another custom command (cy.get('[data-cy=""]')) was efficiently translated to Playwright’s page.locator('[data-testid=""]') FIXME_scrollTo: This native Cypress command, which scrolls the window to a specific position, proved unnecessary in Playwright. Given Playwright’s automatic detection of elements on the page, we opted to remove this command entirely ` Further refinements were made to the converted code, such as removing some "wait/delay" commands. Playwright’s robust handling of asynchronous events allowed us to streamline our tests by eliminating unnecessary pauses enhancing test execution speed and reliability. Conclusion The transition from Cypress to Playwright in our testing framework was driven by necessity but has significantly improved our testing practices. Utilizing a test conversion tool allowed us to migrate our entire suite of E2E tests efficiently, minimizing manual effort and accelerating the adoption of Playwright. Our experience highlights the importance of flexibility and the willingness to embrace new technologies in the face of unexpected challenges. The marked improvements in test execution speed and reliability, along with Playwright's advanced features, have made this transition a resounding success for our team. As we continue to refine our tests and explore the full capabilities of Playwright, we encourage other teams facing similar challenges to consider this approach. The tools and processes outlined here can serve as a roadmap for those looking to enhance their automated testing solutions....

May 31, 2024

3 mins

CypressTestingPlaywright

Understanding the Difference Between `:focus` and `:focus-visible` in CSS

Understanding the Difference Between :focus and :focus-visible in CSS I have learned my fair share about the importance of keyboard accessibility, so I know that visual indication of the focused element is very important. But the well-known :focus pseudo-class is not always the best fit for this job. That's where :focus-visible comes in. Let's look at the differences between these two pseudo-classes and explore the best practices for using them effectively. What is the :focus Pseudo-Class? The :focus pseudo-class is a CSS selector that applies styles to any element that receives focus, regardless of how that focus was triggered. This includes focus events from keyboard navigation, mouse clicks, and touch interactions. Example Usage of :focus ` In this example, the button will display a blue outline whenever it is focused, whether the user clicks on it with a mouse, taps it on a touchscreen, or navigates to it using the keyboard. What is the :focus-visible Pseudo-Class? The :focus-visible pseudo-class is more specialized. It only applies styles to an element when the browser determines that the focus should be visible. This typically occurs when the user navigates via the keyboard or assistive technologies rather than through mouse or touch input. Example Usage of :focus-visible ` Here, the button will only show a blue outline when focused through keyboard navigation or another input method that usually requires visible focus indicators. Key Differences Between :focus and :focus-visible :focus - Behavior: Applies to any element that receives focus, regardless of the input method. - Use Cases: Ensures that all interactions with the element are visually indicated, whether by mouse, keyboard, or touch. :focus-visible - Behavior: Applies styles only when the focus should be visible, such as using a keyboard or assistive technology. - Use Cases: Ideal for scenarios where you want to provide focus indicators only to keyboard and assistive technology users while avoiding unnecessary outlines for mouse and touch users, typically required by design. Accessibility Implications :focus - Pros: - Guarantees that all users can see when an element is focused, which is critical for accessibility. - Cons: - Can lead to a suboptimal experience for mouse users, as focus styles may appear unnecessarily during mouse interactions. :focus-visible - Pros: - Enhances user experience by showing focus indicators only when necessary, thus keeping the interface clean for mouse and touch users. - Tailors the experience for keyboard and assistive technology users, providing them with clear visual cues. - Cons: - Additional considerations may be required to ensure that focus indicators are not accidentally omitted, especially in older browsers that do not support :focus-visible. - There may be cases where you want to show focus indicators for all users, regardless of input method. Best Practices for Using :focus and :focus-visible To achieve the best accessibility and user experience, combining both :focus and :focus-visible in your CSS is often a good idea. Combining :focus and :focus-visible ` Here is a Stackblitz example of what such styling could look like for you to try out and play with. Additional Tips - Test with Keyboard and Assistive Technology: Ensure that your web application is navigable using a keyboard (Tab, Shift + Tab, etc.) and that focus indicators are visible for those who rely on them. It's never a bad idea to include accessibility testing in your e2e testing suite. - Provide Clear Focus Indicators: Make sure that focus indicators are prominent and easy to see. A subtle or hard-to-spot focus indicator can severely impact accessibility for users who rely on keyboard navigation. Conclusion The :focus-visible pseudo-class offers a more refined way to manage focus indicators, improving accessibility and user experience, particularly for keyboard and assistive technology users. By understanding the differences between :focus and :focus-visible, and applying best practices in your CSS, you can create more accessible and user-friendly web applications. Remember, accessibility should never be an afterthought. By thoughtfully applying focus styles, you ensure that all users, regardless of how they interact with your site, can easily navigate and interact....

Nov 8, 2024

3 mins

AccessibilityCSSPlaywright

Let's innovate together!

We're ready to be your trusted technical partners in your digital innovation journey.

Whether it's modernization or custom software solutions, our team of experts can guide you through best practices and how to build scalable, performant software that lasts.

Efficiently Extract Object References in Shopify Storefront GraphQL API

Efficiently Extract Object References in Shopify Storefront GraphQL API

Introduction

The Situation

Solution

Conclusion

William Mimura

You might also like

Setting Up a Shopify App: Retrieving Fulfillment IDs

How to create and use custom GraphQL Scalars

Our Journey from Cypress to Playwright for E2E Testing

Understanding the Difference Between `:focus` and `:focus-visible` in CSS

Let's innovate together!

You might also like

Setting Up a Shopify App: Retrieving Fulfillment IDs

How to create and use custom GraphQL Scalars

Our Journey from Cypress to Playwright for E2E Testing

Understanding the Difference Between `:focus` and `:focus-visible` in CSS