You've now used the GraphQL playground to write queries which fetch data. Now you're probably itching to see how you can add one to a Site!

Last time, we looked at how to use filter to refine your queries so that they only return results matching particular criteria. 

So far we've been working in GraphiQL, the interative playground. This time, we'll run a GraphQL query on your Starter Site. We'll also take a quick look at how to handle the results- but you can learn more about this by following our Documentation on Dot Notation and Collections.

The best way to run your GraphQL query on a Site is to save the query inside a GraphQL file. This keeps it tidy and allows you to easily re-use the same query elsewhere on the Site should you need to.

If you're following this tutorial with the same Site each time, you'll already have a project folder. After all, we have been using the .siteglide-config file in your Project Folder to interact with the GraphiQL interactive playground.

In this example, my project folder

We need to add a GraphQL query inside a specific folder in order to refer to it with Liquid. Before we do that- we need to see your Site's File Structure so we know where to add the folder.

In terminal, you'll need to change directory to the Project Folder.

If you've not already, run a pull command in terminal to pull down the current file structure: siteglide-cli pull my_environment_name

If you want to refresh your memory on using the Siteglide-CLI, you can learn more here.

I'll be using Microsoft Visual Studio Code in this example. Other Editors are available.

All the folders and files that can be synced with your Site are in the marketplace_builder folder.

Open up the marketplace_builder folder. If you've not already got a folder inside this called graph_queries , create one now.

Create a new file to store your query inside. It's best to give the file the exact same name as your query. This will make it easier to find later.

The file should have the extension .graphql.

So that file now exists on your device, but not yet on your Site. You'll need to either sync or deploy the file to your Site.

The choice of command is up to you. sync will watch for changes in the marketplace_builder folder, so you'll need to make a change in the file after running the command before your file is uploaded. The sync command will continue to watch and sync files until you cancel it. deploy will simply deploy all your local files to the Site as a one off command. 

Here, I'll use sync: 

This query file will not be visible in Code Editor, but the files will be on the server and Liquid will be able to access them. The reason for not displaying them here is to hide the most complex code from areas where Clients and non-developers can access it. This might change in the future.

If you wanted to check if the file has synced correctly, you can turn off sync, delete the file and run a pull command. In our experience, there's no need to run this check, as sync will tell you if a file is synced and "done" accurately.

We'll use the graphql Liquid tag provided by platformOS.  You may see other developers familiar with platformOS using tags like query_graph or execute_query, but graphql is the most up-to-date: {% graphql my_results = "get_items_with_musical_names" %}

Notes:

You can output all of your results on the Page, using Liquid output syntax {{ }} to output the variable we defined earlier.

Notes:

The results will output in Hash format. You can use dot notation to access specific results within the Object.

This example uses dot notation. 

It is possible to use your Query to rename the keys in your Results- doing this would require different dot notation. We'll look at this later. 

For now, we'll be using the query below, which does not rename any keys. I've set per_page to 2, in order to make the example data Object shorter and easier to read. Code:

My Page returns the following results- don't worry- there's no need to read them in this form:

Running these results through a 3rd-party JSON parser gives me the data in a format which is much easier to read. We don't recommend any particular JSON parser, but if you're using a text editor there will normally be an extension available which does this.

The structure of the results here matches the results we see in the GraphQL playground. We're looking for the key which returns an array of results- this is indicated by the square bracket [ ]:

The dot notation to reach the results is:

Alternatively, you can always run your query in the GraphiQL Playground and work out the dot notation needed from the results shown in the middle-right panel. You'll just need to ignore the very top key in the results data:  and use the variable from your graphql  tag instead e.g. my_results :

We loop over every item in the Results array. We create a variable called this with a scope which allows it to be accessed only inside each loop iteration. this contains all the data for that result.

In this example, we'll output:

We can now also bring in other Front End languages. I'll add some common HTML tags.

This gets me the following Results on the Page:

You can use a Liquid include tag to output a Layout to display your results. The trick is to make sure that the data fits the same format as the layout is expecting. 

You can learn more about this topic here, as it works in the same way as displaying Collection Results in a Layout.

You've reached the end of the first collection of our Learning GraphQL tutorials.  By now, you should be able to:

New Tutorials will be added soon!

There's no official challenge for this tutorial, because you probably want to experiment with adding queries to your Site. 

In the next Tutorial, we'll look at using variables in your Queries to make them more dynamic. We'll look at how you can use variables:

Let's go!