Tutorial 5 - Using Liquid to run GraphQL queries on your Site

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! prerequisites you've completed the "learning graphql" tutorials 1 4 in order to use graphql results on your page, you'll need to be familiar with dot notation liquid syntax you can get started with learning to use dot notation here you may find that you want to refer back and forth between articles on dot notation and graphql as you continue with your learning you'll need to be familiar with siteglide cli in this tutorial we'll be using siteglide cli to add a graphql folder and sync our new queries up to the site about graphql optional read more about graphql and when it might be best used introduction 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 saving your graphql file 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 step 1) find or create a project folder on your device 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 step 2) use siteglide cli to pull down the site's main file structure 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 step 3) load the project folder in a text editor/ code editor 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 step 4) add a new folder called graph queries open up the marketplace builder folder if you've not already got a folder inside this called graph queries , create one now step 5) create a new file in that folder to store your graphql query inside 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 step 6) use siteglide cli to sync or deploy that file to your site 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 adding the graphql liquid tag 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 the tag itself is graphql the first parameter you give should be a new variable name this will create a liquid variable containing your results you can choose your own name after the equals = sign, you should write the file name of your graphql file, without its file extension or any folders for example, my filename is "get items with musical names graphql" so i remove the extension "get items with musical names" accessing the results you can output all of your results on the page, using liquid output syntax {{ }} to output the variable we defined earlier {% graphql my results = "get items with musical names" %} {{my results}} notes the liquid output must be on any line below the graphql tag you can output this in any liquid file; this includes pages, page templates, headers, footers, layouts, code snippets and workflow/ auto responders the results will output in hash format you can use dot notation to access specific results within the object looping over the results 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 query get items with musical names { records( page 1 per page 2 filter { table { starts with "webapp " } properties { name "name", contains "music" } } ) { total pages results { table properties } } } step 1) output the results as shown above step 2) find the key which holds the main array of results 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 {% graphql my results = "get items with musical names" %} {{my results records results}} 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 step 3) implement a liquid for loop to loop over the results {% graphql my results = "get items with musical names" %} {% for this in my results records results %} {% endfor %} 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 step 4) output properties inside each item's iteration in this example, we'll output the table an example property name an example property webapp field 1 2 this is the second custom field defined in the webapp's structure on starter site we can now also bring in other front end languages i'll add some common html tags {% graphql my results = "get items with musical names" %} {% for this in my results records results %} {{this table}} {{this properties name}} {{this properties webapp field 1 2}} {% endfor %} this gets me the following results on the page outputting layouts 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 congratulations you've reached the end of the first collection of our learning graphql tutorials by now, you should be able to set up a development environment to test graphql queries run graphql queries on a siteglide site understand and use graphql pagination use graphql filters new tutorials will be added soon! next time 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 in the graphiql playground using liquid in a page let's go!