Forem: David Warrington

Building Shopify Section Schemas with JavaScript

David Warrington — Fri, 13 Nov 2020 21:38:51 +0000

The Liquid Schema Plugin allows you to export your Shopify Section schemas from JS and JSON files, in turn allowing you to build your schemas dynamically, share schema partials between several schemas, and benefit from the language support provided by IDEs such as VSCode.

In order to use the plugin, the build system you’re using must be Webpack based, and you must be able to add new plugins to your Webpack setup.
If you just want to set the plugin up quickly, simple installation instructions can be found in the plugin README.

Outlined below are some of the use cases I’ve found the plugin to be really handy for:

Shared Section Schema

It’s common for landing pages across a theme to use one or more sections, however since (for the most part) sections can’t be reused with different settings, this requires section files to be duplicated for use on new landing pages. Unfortunately, it can become difficult to maintain multiple of the same schema in this way, because if one needs to be updated, you must remember to update each copy of the schema. Over time this can lead to multiple section schemas, each with slight differences.

As an example, take the following use case: a landing page needs to be created for a new “Spring Summer 2021” range. The page requires that the same components are available as on an existing “Autumn Winter 2020” page. In order to ensure the section schema remain in sync here, you’d first move the schema from the Autumn Winter 2020 section file to its own schema file. Let’s say seasonal-landing.js for now. It would look something like this:

module.exports = {
  name: 'Seasonal Landing',
  settings: [
    // section settings…
  ],
  blocks: [
    // section blocks…
  ]
}

From here, you would replace the schema tag in your existing liquid file with this:

{%  schema 'seasonal-landing' %}

Now the plugin will inject the object exported by seasonal-landing.js into your section file. All you need to do is duplicate the section file and rename it for the Spring Summer 2021 section. If you ever need to update one of the schemas, all sections with the above schema tag will get the same updates with no extra work.

Using a section as a section block

Occasionally you might build a component as a section, which needs to be repurposed as a section block elsewhere. To do this, move the settings array into its own JS file, and import it back into the original schema. The settings can then be imported into another section too.

As an example, let’s say we have a hero banner section that needs to be added as a block for one of our landing pages. First, we move the hero banner settings into their own file, then import them into the original hero banner schema:

// partials/hero-banner.js
module.exports = [
  // section settings…
]

// hero-banner.js
const settings = require('./partials/hero-banner.js')

module.exports = {
  name: 'Hero Banner',
  settings
}

We’d then add the same settings to our new landing page schema like so:

// landing-page.js
const heroBannerSettings = require('./partials/hero-banner.js')

module.exports = {
  name: 'Landing Page',
  blocks: [
    {
      name: 'Hero Banner',
      type: 'Hero Banner',
      settings: heroBannerSettings
    }
  ]
}

Common Fieldsets

I often find myself repeating the same fields within several schemas across a theme. Take for example a link. Shopify doesn’t have a fieldtype with both a text input and URL input yet (it looks like it is coming though), so for every section where we need to add a link, we need to add an input for customising the link text and an input for setting its URL. This can be achieved like so:

// partials/link.js
module.exports = [
  {
    label: 'Link Text',
    id: 'link_text',
    type: 'text'
  },
  {
    label: 'Link URL',
    id: 'link_url',
    type: 'url'
  }
]

// hero-banner.js
const linkSettings = require('./partials/link')

module.exports = {
  name: 'Hero Banner',
  settings: [
    {
      label: 'Title',
      id: 'title',
      type: 'text'
    },
    …linkSettings
  ]
}

Now throughout all our schemas, we can add the same fields for any and all links. If we ever want to add another option, for example to add a selector for the link style, or the link colour; it can be added to this partial and every schema that uses this partial will get those extra options.

Looping Fieldsets

Consider the previous example, but imagine the hero banner needs to support 2 links as opposed to 1. First of all we’d change the link partial to a function where we can specify the number of links we need to have available.

// partials/link.js
const createLinks = (total = 1) => {
  return new Array(total).fill(null).flatMap((_, index) => {
    const currentIteration = index + 1
    return [
      {
        label: `Link Text ${currentIteration}`,
        id: `link_text_${currentIteration}`,
        type: 'text'
      },
      {
        label: `Link URL ${currentIteration}`,
        id: `link_url_${currentIteration}`,
        type: 'url'
      }
    ]
  })
}

Now we change the hero banner schema:

// hero-banner.js
const createLinks = require('./partials/link')

module.exports = {
  name: 'Hero Banner',
  settings: [
    {
      label: 'Title',
      id: 'title',
      type: 'text'
    },
    …createLinks(2)
  ]
}

Adding section-specific schema

The plugin will run functions exported from injected JS modules. These functions are passed the filename and schema tag content as parameters. This means if you need to make any section specific overrides, you can do so in the section file itself. This is commonly used to name specific sections. For example if you have multiple landing pages with the same schema, you might want to give each their own name. To do this you might do the following:

// autumn-winter-2020.liquid
{% schema 'landing-page' %}
{
  "name": "Autumn Winter 2020"
}
{% endschema %}

// spring-summer-2021.liquid
{% schema 'landing-page' %}
{
  "name": "Spring Summer 2021"
}
{% endschema %}

// landing-page.js
module.exports = (filename, content) => {
  name: content.name,
  // settings…
}

Note that you could also use the filename for this. The JSON contained within the schema tag is generally easier to use though.

What other benefits does the plugin provide?

The plugin isn’t only useful for sharing schema across multiple sections and building them dynamically. Since Shopify development is a relatively niche area, there’s a lack of tooling support for really making schemas easy to write and edit. Fortunately, the content of a schema tag is just JSON. By moving the schemas to JSON and JS files, we can benefit from much greater language support within our code editors.

If you’ve ever had to edit a particularly long schema, you might have found that it’s really difficult to keep track of where you are. Even if the indentation is perfect, the number of brackets required to represent arrays and objects can make a long JSON file difficult to navigate. In section schema specifically, I have often found it difficult to keep track of which block type I’m editing the settings array for. Fortunately, JSON and JS files can take advantage of code folding, which allows us to hide large quantities of code so that we can more easily visualise the schema structure. If that’s too difficult, VSCode (and I’d assume other editors too) can provide a breadcrumb style breakdown of exactly where in the object your cursor sits, which can make navigating a large schema really easy.

Finally, it’s often bugged me in the past just how easy it is to make a mistake within a schema. Be it a trailing comma at the end of an array, or simply forgetting to wrap a key in quotes. Using actual JSON or JS files for the schemas lets us forget about this issue for the most part. Since our editor knows we’re trying to write valid JSON, or JS, it will warn us where we’ve made a mistake.

It all boils down to time and effort

Detailed above are a number of practical ways in which section schemas can be built dynamically. Ultimately I find each of these saves me time and effort when building Shopify themes. Be that in the immediate term, or a few months down the line.

Section schemas are typically presented to us as being the same concern as the section itself. By creating them outside of your section files, it becomes easier to understand them simply as a group of fields that can be generated by a program. You might build a function capable of outputting a huge variety of different schemas, or you might simply use it to keep 2 or 3 section schemas in sync. In my experience, I have yet to work on a Shopify theme where building my section schemas in JS had no benefit at all.

If you would like to use the Liquid Schema Plugin on your project, please check the GitHub repo.

davidwarrington / liquid-schema-plugin

Build reusable section schemas using Javascript

Liquid Schema Plugin

This plugin allows Shopify section schema to be imported from JavaScript or JSON files into Liquid sections. It is compatible with any Webpack based build system. This allows you to build partials that can be shared across multiple sections and applied in different contexts such as section blocks or settings.

Installation

Install using yarn:

yarn add --dev liquid-schema-plugin

Or npm:

npm install --save-dev liquid-schema-plugin

Slate v1

Add the plugin to slate.config.js

const LiquidSchemaPlugin = require('liquid-schema-plugin');

module.exports = {
    // ...
    'webpack.extend': {
        plugins: [
            new LiquidSchemaPlugin({
                from: {
                    liquid: './src/sections',
                    schema: './src/schema'
                },
                to: './dist/sections'
            })
        ]
    }
}

Webpack

Add the plugin to webpack.config.js

const LiquidSchemaPlugin = require('liquid-schema-plugin');
module.exports = {
    // ...
    plugins: [
        // ...
        new LiquidSchemaPlugin({
            from

…

View on GitHub

Creating a Twitter module for your Nuxt app

David Warrington — Fri, 01 Nov 2019 21:28:57 +0000

This tutorial covers how to integrate a Twitter feed into a statically generated Nuxt site. We’ll be using Node to pull tweets from Twitter, and IFTTT to rebuild our statically generated site on Netlify every time we tweet.

A demo repo can be found here in case you have any issues following the tutorial: https://github.com/davidwarrington/nuxt-tweet

1. Setup

The modules we’ll be using are:

twitter - Which will make connecting to the Twitter API painless.
fs-extra - This is optional. You can use the built-in fs Node module, but fs-extra makes things a little easier, by removing the need to manually check for pre-existing files and other boring tasks. For this reason we’ll use it in this tutorial.
dotenv - This is used to inject API keys that we don’t want to expose publicly for use during the build process. If you’re already using the @nuxt/dotenv module, you can skip installing this.

If you’re using yarn, run:

yarn add --dev twitter fs-extra dotenv

Or if you’re using npm, run:

npm install --save-dev twitter fs-extra dotenv

Finally, this step is optional, but if you don’t want to fill you commit history with JSON files containing tweets, add tweets/ to your .gitignore.

2. Creating the Twitter Client

To begin with, we need to make sure that we can connect to Twitter. Sign in to developer.twitter.com and create an app. This will allow us to generate API keys, in turn allowing us to pull information from Twitter. Once you’ve created the app, open it and visit the Keys and Tokens tab. You will need both Consumer API keys and Access Tokens. So you will have to make sure both are generated.

Now onto the code: create a modules folder and a twitter.js file inside. This module is going to run every time we run either the generate or dev scripts. This means that when we’re developing locally, Nuxt will pull the latest tweets from our feed and they will be deployed to the live site each time it is rebuilt.

Before we make the Nuxt module itself, let’s build the Twitter client to ensure that we can pull the info from Twitter.

To begin with add the following lines of code to your modules/twitter.js:

const Twitter = require('twitter')
const fs = require('fs-extra')

const client = new Twitter({
  consumer_key: '[CONSUMER KEY]',
  consumer_secret: '[CONSUMER SECRET]',
  access_token_key: '[ACCESS TOKEN]',
  access_token_secret: '[ACCESS TOKEN SECRET]'
})

We’ve just imported the Twitter module, which will allow us to easily configure Node to connect to the Twitter API. We’ll use the fs-extra module, which we’ve named fs , to save the data we pull from Twitter in a JSON file.

Replace the string values in client with your API keys and the Twitter module will be able to connect to the API.

From here add the following code:

const endpoint = 'statuses/user_timeline'
const params = {
  screen_name: '[YOUR USERNAME]',
  include_rts: false
}
const callback = (error, tweets, response) => {
  if (!error) fs.outputJSON('./tweets.json', tweets.slice(0, 5), { spaces: 4 })
}

client.get(endpoint, params, callback)

The endpoint is the part of the API we want to connect to. Since in this tutorial we’re getting tweets from our own timeline, the endpoint we’re using is statuses/user_timeline.

The params are options we’re sending to configure the endpoint. Since we want our own tweets, the screen_name property is our own twitter handle (excluding the @) and include_rts just prevents it from including retweets.

The callback tells the client what to do with the tweets it pulls from the API. We only need to use the first two arguments in our module, however I like to include all that are available in case I want to change it later on. In the function we’re simply saying “if the API doesn’t respond with an error, write the tweets to ./tweets.json, using 4 spaces for indentation to make it nice and readable”. I’m slicing the response to only include the latest 5 tweets. If you want to show more, or even all of the tweets it returns, feel free to replace tweets.slice(0, 5) with whatever you need.

Now to test our API connection. In your terminal, navigate to your modules directory and run node twitter. This should run the script we’ve just created. If all has gone well, once the script finishes, you should have a tweets.json file which contains an array of your tweets, which you should delete to prevent committing them unnecessarily. If not, go back through the previous steps to make sure you’ve not missed anything.

3. Building the Nuxt module

From here, converting our Twitter script into a Nuxt module is relatively simple. At the end of your twitter.js module, write the following:

export default function NuxtTwitter(config) {
    this.nuxt.hook('build:before', generator => {
        client.get(endpoint, params, callback)
    })
}

Delete the client.get(endpoint, params, callback) line we’d previously added in the JS file, as we now only need it inside the module we’re exporting.

Similarly to before, we’re not making use of either the config or the generator arguments that are passed to the module, but they’ve been included anyway, in case we want to expand the module later.

In case you’re interested, config, in this example, is passed in via the modules array in your nuxt.config.js. When declaring which modules are to be used by Nuxt, the modules array can either accept strings, which are just the module names, or it can accept arrays. The first value in these arrays is the location of the module and the second value in these arrays is the data passed as our config argument.

The generator argument passed to our callback in the nuxt.hook contains a lot of information about the whole process. By accessing generator.options you can access your nuxt.config.js. It’s worth running the module and either logging generator to your console or printing it to a JSON file for a closer inspection. generator.options is the method used by a lot of modules to pass module options from within nuxt.config.js, but outside of the modules array.

By using this.nuxt.hook we are able to tell Nuxt to run a function when it hits a certain “hook”, which refers to a stage in its process. The first parameter: build:before, represents the stage at which to run the function. The build stage is used by both generate and dev command processes, so it covers both bases. We need to run this before we build the site, because we need to be able to import the JSON data in order to use it within our site.

Also change the first argument in your fs.outputJSON() method call from ./tweets.json to ./tweets/tweets.json.

4. Setting up Nuxt modules

Our nuxt.config.js should be exporting a config object. Find the modules property in this object. If you don’t have one, create it. The modules property is an array that tells Nuxt which modules to load when it runs. Add the file path and name to help Nuxt find your module. You can omit the .js extension in your module name. It should look like this:

module.exports = {
    // other config properties

    modules: [
        'modules/twitter'
        // any other modules used in your build
    ]
}

So now, if we run yarn dev, yarn generate, npm run dev or npm run generate, depending on which package manager takes your fancy, we should find that Nuxt creates the JSON file for us. This allows us to import the data from this file into any pages/components we need.

5. Securing our API keys

Before we go pushing any of our code to public repos, let’s hide the API keys so that nobody else has access to them. If you’ve not already installed dotenv, do so now. In the root of our project, create a file called .env. By default, dotenv will take keys from this file and add them to Node’s process.env, which is part of any running Node process.

Your .env file should look something like this:

CONSUMER_KEY=
CONSUMER_SECRET=
ACCESS_TOKEN_KEY=
ACCESS_TOKEN_SECRET=

Now move the keys we added to our twitter.js client to this file, assigning them to the relevant variable. Once this is done, we’ll replace the client declaration in our twitter.js module with the following:

const client = new Twitter({
  consumer_key: process.env.CONSUMER_KEY,
  consumer_secret: process.env.CONSUMER_SECRET,
  access_token_key: process.env.ACCESS_TOKEN_KEY,
  access_token_secret: process.env.ACCESS_TOKEN_SECRET
})

We’ll also add the following beneath our Twitter and fs requires at the top of our module file:

const dotenv = require(‘dotenv’)
dotenv.config()

By importing dotenv and calling it’s config() method, we’re adding the contents of .env into process.env, which can be accessed by Node.

Also, add .env to your .gitignore if it’s not already included. This will stop you committing the file to your repo.

6. Importing Tweets into Nuxt

With our API keys hidden away and our tweets being written to a JSON file correctly, we can now use them in our build. Just to demonstrate this, we’ll create a list of tweets on our index page. Open pages/index.vue and replace all code in the file with:

<template>
  <ul>
    <li
      v-for="tweet in tweets"
      :key="tweet.id"
    >
      {{ tweet.text }}
    </li>
  </ul>
</template>

<script>
import tweets from '@/tweets/tweets'

export default {
  data() {
    return {
      tweets
    }
  }
}
</script>

If you run yarn dev or npm run dev, you should find that the index page just lists your 5 latest tweets. Our template is importing them via the import tweets from @/tweets/tweets line in index.vue.

7. Deploying our site

In order to get our site live we need to use a deployment tool that can be triggered via webhooks and supports adding environment variables. For the purposes of this tutorial we’re going to use Netlify.

First of all, create a Netlify account if you don’t have one already. After this, choose New site from Git on Netlify App. From here we need to connect Netlify to our repository. Choose the Git provider and follow the set up process to launch your site. Netlify will deploy our site by pulling the git repository and serving our chosen folder.

In the build settings, set the build command to yarn generate and set the publish directory to dist.

Deploying from our site won’t work immediately because we need to add the API keys we hid with dotenv. In the site settings find Environment variables and add the same variables you have in your .env file.

8. Setting up deployment webhooks with IFTTT

What’s the use in having a Twitter feed on our site if it doesn’t update when we tweet? We’re going to use IFTTT to solve this problem. For anyone who doesn’t know, IFTTT is a service that allows us to automate tasks with “recipes”. We’re going to have a recipe that says “When I tweet, send a request to a predetermined URL”. When Netlify receives this request, it will build the site again, causing our Nuxt module to update the list of tweets.

First of all add a build hook in the Continuous Deployment section of your Netlify site build settings, like so:

Now create an account on IFTTT. Once done, create a new applet by visiting IFTTT.com/create. We’ll use Twitter as our “this” trigger. Follow the process on IFTTT to connect it to our account and choose the “New Tweet by you” trigger. The “that” action should then be the webhooks service. Use the service to “make a web request”. Copy the URL for your Netlify build process, change the method to POST and then finish creating the applet.

Now, post a tweet to test that everything has worked. If it has, you should see a new deployment on the deploys page of your Netlify site.

Congratulations! You’ve now integrated a twitter feed into your statically generated Nuxt site and learned how to create your own Nuxt module.

You can see the result of this tutorial in the twitter feed at the bottom of each page of my site. I've sliced the tweets array to only show the 3 latest tweets though.

If you had any issues following this tutorial, please take a look at this demo Git repo. The commit history for which shows all of the steps taken in this tutorial.

Repo