Forem: Seb Scholl

Simple CI/CD for 8base Custom Functions

Seb Scholl — Wed, 22 Apr 2020 14:32:52 +0000

One of 8base's most powerful features is the use of Custom Functions. They allow developers total flexibility for writing server(less) side code, whether it's for a simple GraphQL resolver or a data-heavy scheduled reporting job. Put simply, custom functions extend the full power of NodeJS to your 8base workspace.

That said, deploying custom functions can get tricky when multiple developers are collaborating on a workspace. If all team members have deploy privileges, it's easy for one developer to accidentally overwrite another's work.‍

Because of this, we recommend that you set up a CI/CD script that handles the deployment of custom functions to a workspace. By doing so, you remove the risk of engineers overwriting each others work, as well as create a single source of truth for your most up-to-date code; the repository!

Tutorial

In this tutorial, we're going to go over setting up a simple CI/CD script on GitHub using Actions. Additionally, we will configure the roles and permissions needed to allow automatic deployment, as well as protect developers from overwriting deployed code.

Step 1. Setting up the Roles

The first role we're going to create is the Developer role. This is the role that you'll assign any existing and new developers when they are invited to your project workspace.

While the permissions that you choose to grant these developers may vary from workspace to workspace, ensure that the Deploy permission - found in the Roles > Developer > APPS tab - is unchecked. This will make sure that developers are unable to deploy custom functions directly to a workspace using the 8base CLI.

‍

The second role we're going to create is the GitHub_Deploy role. This is the role that we'll assign to an API Token that gets stored securely in GitHub.

For this role, ensure that the Deploy permission - found in the Roles > GitHub_Deploy > APPS tab - is checked. All other permissions can be turned off. This permission allows the CI/CD script to deploy custom functions.

Step 2. Creating an API Token

Navigate over to Settings > API Tokens and create a new API Token called GITHUB_DEPLOY_TOKEN. While creating it, make sure to associate the GitHub_Deploy role that you just created.

The token generated can only be seen once. Make sure to copy and save it somewhere safe for the time being, or be ready to repeat this step later. Either way, this token is what we'll use to authenticate against the 8base API in our GitHub Action script.

Step 3. GitHub Actions

GitHub Actions makes it easy to automate all your software workflows by leveraging CI/CD. With the following script, we're going to make sure that whenever a merge is made into the master branch of our repo, our updated project code gets deployed to 8base.

‍

name: 8base Deploy Custom Functions
on:
  push:
    branches:
      - master
env:
  EIGHT_BASE_API_TOKEN: ${{ secrets.EIGHT_BASE_API_TOKEN }}
  EIGHT_BASE_WORKSPACE_ID: ${{ secrets.EIGHT_BASE_WORKSPACE_ID }}
  CI: true
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install 8base-cli
        run: sudo npm i -g 8base-cli
      - name: Deploy to 8base
        working-directory: ./server
        run: |
          8base login --token ${{ env.EIGHT_BASE_API_TOKEN }}
          8base configure --workspaceId ${{ env.EIGHT_BASE_WORKSPACE_ID }}
          8base deploy

The YAML code should be added to a file located at the path .github/workflows/deploy.yml - in relation to the root directory of your project. The working-directory key indicates that the 8base project code exists in a directory located at ./server - which may change based on your own directory structuring. If you're 8base.yaml is located at the\ root of your repo, remove the working-directory option.

Step 4. Setting Secrets in GitHub

In order for the Action script to access required deploy credentials, we must set them in GitHub.

‍
While in your project's repo on GitHub, navigate to Settings > Secrets and add a new secret. There are two different secrets we need to set.

EIGHT_BASE_WORKSPACE_ID - The ID of the 8base workspace to which you want your code to be deployed.
EIGHT_BASE_API_TOKEN - The API Token that was generated in step two. ‍ Once these values are all set, go ahead and commit and push to GitHub all the changes that have been made to your custom functions!

Wrap Up

On your next merge or push to the remote master branch, GitHub will detect the newly added Action script. Should all steps be successfully completed, you'll quickly see the script successfully run and code deployed.

‍

Loose Typings in GraphQL for Dynamic Grouping and Aggregation Queries

Seb Scholl — Tue, 07 Jan 2020 16:20:21 +0000

Several months ago a developer building on 8base reached out via Intercom with, what ended up being, a roadmap changing message. It read:

...I'm building a marketing campaign management system that's integrated with my eCommerce business. I've gotten the whole thing working, but feel stuck when it comes to generating good reports. Is there any way I can do aggregations through the GraphQL API like I can when using SQL?

The 8base team had a few cursory ideas on how to approach this problem. However, having to work within the confines of the GraphQL specification invalidated a number of the initially suggested approaches. That said, we felt that this wasn't the last time a developer would wish they had such a feature. So as a result, "Groupings and Aggregations" was added to the top of our development team's to-do list.
‍
Before taking some time to talk about how we were able to achieve groupings and aggregations within the confines of GraphQL, let's first check out these new API features themselves. We'll use a simplified data model that's similar to the one the developer who reached out was using.

The Data Model

Every order being made on the eCommerce site triggered a webhook that created an Invoice record in 8base. Additionally, Invoices are associated with a Campaign record when applicable (within the campaign's start and end dates). Thus we have our two tables with the following fields defined.

Campaigns
• Name: Text
• StartDate: Date
• EndDate: Date
• Discount: Number
• Invoices: Table (has-many relation)
‍
Invoices
• OrderName: Text
• OrderDate: Date
• OrderPrice: Number
• Campaign: Table (belongs-to relation)
‍
Simple enough! Right? Now with this data model defined, we can start writing some pretty useful queries - whether they're for reports, chart-data, or whatever else.

Comparing Campaign Performance

We filled the database with about 600 fake invoices and several campaigns. Using grouping and aggregations, we're going to run a query that gives us the following information back.

The ID, Name, and Creator's email of each campaign.
The number of Invoices attributed to each campaign.
The average sale price and total revenue generated by each campaign.
The order number of every Invoice in each group. ‍ In order to accomplish this, we're going to use the following query. Pay attention to the inline comments, as well as notice the relationships between "as" declarations and the GraphQL response object keys that are being set to type values.

query {
  invoicesList(groupBy: {
    query: {
      # We'll be grouping by Campign ID 
      # while aliasing the Name field as well.
      campaign: {
        id: { as: "CampaignId" },
        name: { as: "CampaignName"},
        # Jump into the owner relationship and 
        # alias the email field.
        createdBy: {
          email: { as: "CampaignOwner" }
        }
      },
      # On a single field we can run multiple
      # aggregations. For example, both summing
      # and averaging all prices in each group.
      orderPrice: [{
        as: "AverageSalePrice",
        fn: { aggregate: AVG }
      }, {
        as: "TotalRevenue",
        fn: { aggregate: SUM }  
      }],
      # Using the _groups key, we can access the
      # list of records used in the grouping function.
      # This can would on any level/relationship
      _group: { as: "Invoices" }
    }
  }) {
    groups {
      # The idea of "Loose Typings" come into play in
      # that the API cannot know ahead of time what
      # value types an aggregated result will be. Therefore
      # the developer can declare them explicitly in the query.
      CampaignId: ID
      CampaignName: String
      CampaignOwner: String
      AverageSalePrice: Float
      TotalRevenue: Float
      # On the _group we can re-access the records used
      # in the group on the normal record list types.
      Invoices: InvoiceGroup {
        count
        items { orderNumber }
      }
    }
  }
}

While the syntax may look a little funky, a deceivingly powerful SQL statement gets generated in the background that fulfills the query. Notice how, for every value that we aliased using as in the groupBy query itself, we were able to use the name as a key in the response object while assigning a type on the fly - without it mattering whether the field or aggregate value, was on the primary or a related table!

‍Running this query, we get the following JSON response from the 8base GraphQL API.

‍{
  "data": {
    "invoicesList": {
      "groups": [
        {
          "CampaignId": null,
          "CampaignName": null,
          "CampaignOwner": null,
          "AverageSalePrice": 49.804094,
          "TotalRevenue": 17033,
          "Invoices": {
            "count": 342,
            "items": [
              { "orderNumber": "000099" },
              // 341 other orderNumbers
            ]
          }
        },
        {
          "CampaignId": "ck4mza2pt00hs07mh0jli1hj9",
          "CampaignName": "Summer Sale",
          "CampaignOwner": "melissa@candleshop.com",
          "AverageSalePrice": 50.686567,
          "TotalRevenue": 3396,
          "Invoices": {
            "count": 67,
            "items": [
              { "orderNumber": "000256"},
              // 66 other orderNumbers
            ]
          }
        },
        {
          "CampaignId": "ck4mz9g2r00ax07ju6v8a6oaj",
          "CampaignName": "November Madness",
          "CampaignOwner": "jenny@candleshop.com",
          "AverageSalePrice": 46.953125,
          "TotalRevenue": 3005,
          "Invoices": {
            "count": 64,
            "items": [
              { "orderNumber": "000461" },
              // 63 other orderNumbers
            ]
          }
        },
        {
          "CampaignId": "ck4mz8sgw009c07juevcgfcqm",
          "CampaignName": "Christmas Blowout",
          "CampaignOwner": "james@candleshop.com",
          "AverageSalePrice": 50.128713,
          "TotalRevenue": 5063,
          "Invoices": {
            "count": 101,
            "items": [
              { "orderNumber": "000509" },
              // 100 other orderNumbers
            ]
          }
        }
      ]
    }
  }
}

‍
Now, this is already pretty awesome. However, we can still take it a step further. Let's add some new, and totally believable, requirements to our specification.

Only return groups belonging to a Campaign.
Only return campaigns with an average sale price greater than or equal to $50.00 ‍ In order to achieve this, we're able to use a having clause. This allows us to use predicates that are specified as objects on declared types - using aggregated fields. For brevity's sake, I'll only post the new part of the query. However, know that it must come after the groupBy query argument.

query {
  invoicesList(groupBy: {
    query: { ...queryOptions },
    # Having let's us filter by an aggregated 
    # value using type specific predicates.
    having: {
      AND: [{
        alias: "CampaignName"
        string: { is_not_empty: true }
      },{
        alias: "TotalRevenue"
        float: { gte: 50.00 }
      }]
    }
  }) {
    groups { ...groupOptions }
  }
}

By specifying both the alias - which must match an alias in the query - and the field's expected type, we're able to declare a predicate value that filters the results accordingly on an aggregated/grouped field. As a result, the following filtered response gets returned.

{
  "data": {
    "invoicesList": {
      "groups": [
        {
          "CampaignId": "ck4mza2pt00hs07mh0jli1hj9",
          "CampaignName": "Summer Sale",
          "CampaignOwner": "melissa@candleshop.com",
          "AverageSalePrice": 50.686567,
          "TotalRevenue": 3396,
          "Invoices": {
            "count": 67,
            "items": [
              { "orderNumber": "000256"},
              // 66 other orderNumbers
            ]
          }
        },
        {
          "CampaignId": "ck4mz8sgw009c07juevcgfcqm",
          "CampaignName": "Christmas Blowout",
          "CampaignOwner": "james@candleshop.com",
          "AverageSalePrice": 50.128713,
          "TotalRevenue": 5063,
          "Invoices": {
            "count": 101,
            "items": [
              { "orderNumber": "000509" },
              // 100 other orderNumbers
            ]
          }
        }
      ]
    }
  }
}

‍

How it works?

It might be hard to appreciate these queries without being somewhat familiar with SQL. That said, each of these groupBy GraphQL queries generates a raw SQL statement that could make a lumber-jack cry. For example, our query above generates the following SQL statement.

‍

SELECT GROUP_CONCAT(DISTINCT `MT`.`id`) AS `_grouping`, 
            AVG(`MT`.`orderPrice`) AS `AverageSalePrice`, 
            SUM(`MT`.`orderPrice`) AS `TotalRevenue`, 
            `campaign`.`id` AS `CampaignId`, 
            `campaign`.`name` AS `CampaignName`, 
            `campaign->createdBy`.`email` AS `CampaignOwner`, 
            GROUP_CONCAT(DISTINCT `MT`.`id`) AS `Invoices`
      FROM `8base_5d84e92c`.`Invoices` AS `MT`
    LEFT JOIN (`8base_5d84e92`.`CampaignInvoices` AS `campaign->CampaignInvoices` 
                INNER JOIN `8base_5d84e92`.`Campaigns` AS `campaign`
          ON `campaign->CampaignInvoices`.`campaignBId` = `campaign`.`id`  
                        AND `campaign`.`deletedAt` = 0)
          ON `MT`.`id` = `campaign->CampaignInvoices`.`invoiceAId`
          LEFT JOIN `8base_5d84e92`.`Users` AS `campaign->createdBy`
          ON `campaign`.`createdById` = `campaign->createdBy`.`id`
                        AND `campaign->createdBy`.`deletedAt` = 0
            WHERE `MT`.`deletedAt` = 0 
        GROUP BY `campaign`.`id`, `campaign`.`name`, `campaign->createdBy`.`email` 
        HAVING ((`CampaignName` IS NOT NULL AND `CampaignName` <> '') 
                AND `TotalRevenue` >= 50) 
        ORDER BY `_grouping` ASC LIMIT 0, 5000

With that in mind, essentially what's happening on the GraphQL side is a sophisticated utilization of aliases that allows for dynamic types and attribute-names to be used. On the 8base side, we attempt to auto-cast types in the response. However, this is completely unreliable since there is no way of knowing how a grouped or aggregated field will be returned.

‍This is why it is necessary to explicitly, and manually, specify types in the response object. That way, we're able to enrich the GraphQL schema on the fly to accommodate the dynamic key-value pairs and objects. In tandem with auto-generating a number of custom types ahead of time, such as the GroupByField and a <TableName>Group for every table in the 8base workspace, the grouping and aggregation functions having everything they need to run... and only tease the limits of the GraphQL spec!

{
  # Using the aliased name and explicitly declaring a type, we're
  # able to generate dynamically name object keys.
  groups {
    CampaignId: ID
    CampaignName: String
    CampaignOwner: String
    AverageSalePrice: Float
    TotalRevenue: Float
    # The <TableName>Group type is auto-generated to allow for
    # the aliased group to be accessed as a normal list of records.
    Invoices: InvoiceGroup {
      count
      items { orderNumber }
    }
  }
}

‍

Building an Infinite Scroll Component using VueJS and GraphQL

Seb Scholl — Tue, 03 Dec 2019 18:28:40 +0000

It's hard to think of a web or mobile application in 2019 that doesn't have at least one feed or list component. Whether it's for a news feed, search results page, or tabbed-out list of resources, different methods of pagination are constantly being used. One of the most popular pagination experiences is the infamously addictive Infinite Scroll.

Before we jump into building an infinite scroll component, let's answer one question. Why is infinite scroll – or pagination in general – useful?

Imagine that you're working on a popular news app. There are 10,000's of articles in the archives and dozens being published every day. The news feed in your app sorts articles by publishing date so that the newest appear first. However, sorted or not, if the feed loads ALL articles every time a user opens their app, the infinite scroll feed would instead be an infinite load feed and everyone would be sad.

This is where pagination, in its various forms, comes to save the day. Instead of your feed loading ALL of the news, it's able to quickly request – for example – the 25 most recent articles. Then when the user requests more news the feed will fetch articles 26 through 50 and so on. This makes sure that response times are quick and there is never too much data being needlessly transferred.

Rather just play with the code yourself? it's live on CodeSandbox! Feel free to check it out.

Also... here's the GitHub repo

Getting Started

So with all of that babel in mind, let's actually build an infinite scroll component using VueJS and a GraphQL API. You'll likely be able to re-use the final component in any of your VueJS projects, so think of it as a new tool in your toolbox once done!

Prerequisites

This tutorial assumes that you are:

Somewhat familiar with Vue
Have Node installed on your computer
Use npm or yarn
You are excited about playing with GraphQL!

Using Vue instant prototyping

The most under-valued and epic (in my humble opinion) Vue feature is instant prototyping. What does that mean? It means that without having to set up an entire Vue project you can develop a single component in isolation.

This will let us (almost) immediately jump into developing our component, so let's install it during our short set up section.

Installing the CLI and dependences

First, we're going to install the Vue CLI and an extra extension package that gives us the ability to use instant prototyping.

# Install Vue CLI
npm install -g @vue/cli
# Install the CLI instant prototyping
npm install -g @vue/cli-service-global

Next, create a new directory on your computer and call it whatever you'd like. Here we'll write all the code for our component.

# Create new directory
mkdir infinite-scroll-component
# Change into new directory
cd infinite-scroll-component

Now, we're going to create our component files and an examples directory. Why? Because when developing our component we'll want to import/interact with it like we would in a full application. Thus, the examples directory will allow us to do just that by requiring our infinite scroll component as a local dependency.

# This will create the examples directory and all required files
mkdir examples && touch index.js infiniteScroll.vue examples/default.vue
# Your directory should look like this
tree .
=> 
infinite-scroll-component
├── examples
│   └── default.vue
├── index.js
└── infiniteScroll.vue

Finally, we're going to want to initialize a new NPM project in both the root and examples directory. When doing this, just accept all the defaults before installing the project's dependencies.

# Init new npm project in ROOT directory
npm init
# Install dependencies
npm install --save vue graphql-request
# Change into examples directory and init new npm project
cd examples && npm init
# Require the infinite scroll component as a local dependency!
npm install --save ..

Voila! If only setup was always that easy...

With instant prototyping we can now run vue serve FILE_NAME and it will spin up the development server for that single file. Try it! You will probably be... potentially underwhelmed since our files are still empty 🙃

That said before we start writing our Vue components we're going to set up the GraphQL API. Why? Because it is SO MUCH MORE FUN developing when there's data. Hopefully, you agree!

Setting up a GraphQL API on 8base

There are many different ways to accomplish setting up a GraphQL server and API. However, we'll use 8base so that everything is extremely quick to set up and super stable. To get started, we'll only need to take the following few steps.

1) Sign Up

If you have an existing account, visit your 8base Dashboard and select an existing Workspace. If you don’t have an account, create one on 8base. Their free plan will work for what we need.

2) Building the Data Model

In the workspace, navigate to the Data Builder page and click on “+ Add Table” to start building the data model. Were going to create just one called Articles with the following fields.

Articles

Field	Type	Description	Options
`title`	Text	Article title	`mandatory=True`
`body`	Text	Article body	`mandatory=True`, `characters=1000`

3) Adding Dummy Data

Let's add some dummy records to our database. I've uploaded a DummyData.csv file. Save it and then open the Data tab that's right next to the Schema tab in the 8base Data Builder.

On the far right of the Data Viewer there is a dropdown with an Import CSV option. Select the DummyData.csv file from your downloads folder and make sure to specify "Has Header Row" in the modal that appears. You might need to map the column names to the appropriate table fields. However, once done, the import should only take a few seconds.

4) Roles and Permissions

To allow our app to securely access the 8base GraphQL API with appropriate permissions were going to create an API Token with a custom role attached. Navigate to Settings > Roles and create a new role with the name "FeedAppClientRole". Once created, click the role to update its permissions.

Here we can update what permissions the FeedAppClientRole is allowed. In our case, we ONLY want it to be able to query/read articles. Let's check/uncheck the appropriate boxes to enforce that.

FeedAppClientRole Permissions

Table	Create	Read	Update	Delete	Fields
Articles	False	All Records	No Records	False	Full Access

Now we need to attach this role to an API Token that can be added to our app. Navigate to Settings > API Tokens and add a new token by giving it a name and selecting under "Roles" the FeedAppClientRole that we just created.

Make sure to copy the API token once created! You won't be able to view it again.

5) Getting the Workspace API Endpoint

Finally, let’s copy our workspace’s API endpoint. This endpoint is unique to our workspace and is where we will send all of our GraphQL queries for new records.

There are a few ways to obtain the endpoint. However, just navigate to the workspace Home page and you’ll find the endpoint in the bottom left.

6) Testing that it works!

We should probably test that our API is properly set up before we keep going. How, you might ask? By querying it! Instead of setting up or using some GraphQL client, let's just run a good 'ol fashion curl command in our terminal and view the response.

Make sure to replace <YOUR_API_ENDPOINT> with your workspace API endpoint and <YOUR_API_TOKEN> with the API Token you created.

curl -X POST '<YOUR_API_ENDPOINT>' \
     -H "Content-Type: application/json" \
     -H 'Authorization: Bearer <YOUR_API_TOKEN>' \
     -d '{ "query": "{ articlesList(first: 10) { items { title } } }"}'

Does the JSON response show a list of article titles? Woo hoo! Nice work. We're now ready to keep cruizing and move into the creating the component.

Setting up the component

So, let's quickly list out what our infinite scroll component is going to have to do. That way we'll be able to think more clearly about the steps we need to take.

Simple Spec

Query a GraphQL endpoint for N many records.
Allow the user to scroll vertically through a rendered list.
Recognize when the user has reached the end of the list.
Query N additional records and append them to the list.
Allow for the developer to specify a template for list items.

With these bullets in mind, let's add some code to our files so that we have a structure to work with.

`examples/default.vue`

Again, the reason that we have the examples/default.vue file is so we can import the component being developed like we would in a full application. Go ahead and run vue serve examples/default.vue – or vue serve default.vue, if you're already in the examples directory. This will spin up the instant prototyping development server. You may see some errors while making incremental file updates; just ignore them for now.

Per our simple spec, we want an infinite scroll component that fetches a specified number of records from a GraphQL API. Additionally, we want to be able to specify a template that will get rendered for each record that's fetched.

With that in mind, let's create an example of how we'd like to use our component. Always read the in-code comments!

<style scoped>
* {
  font-family: Arial, Helvetica, sans-serif;
}

.container {
  margin: 0 auto;
  width: 420px;
}
</style>

<template>
    <!-- 
      Here's our InfiniteScroll component. We want to pass it some simple props so that the component knows... 

      1) query: The GraphQL query to run. 
      2) limit: How many records to fetch.
      3) respKey: A key for accessing the response.
      4) endpoint: Where to fetch the records from.
      5) authToken: If needed, a token to access the API.
     -->
     <section class="container"> 
      <InfiniteScroll 
          :query="query"
          :limit="limit" 
          :respKey="respKey" 
          :endpoint="endpoint" 
          :authToken="authToken">
          <!-- 
            Instead of being stuck with a generic template, we want to be able to render out each record that gets fetched with a
            custom template. 

            1) Using v-slot we can name the scoped data that's passed to the template.
            2) The template is a child component of InfiniteScrollm so we can access it using <slot />
          -->
          <template v-slot="item">
              <!-- 
                Using the scoped slot data, we're creating a simple template that will render out the wanted data from our fetched records.
                -->
              <article>
                <h4>{{ item.title }}</h4>
                <p>{{ item.body }}</p>
              </article>
          </template>
      </InfiniteScroll>
    </section>
</template>

<!-- 
  Next up... <script> will go here 
-->

Sweet! We essentially just typed out how we'd like to use our InfiniteScroll component. It looks pretty intuitive, right? Now we have to ACTUALLY BUILD IT... Before that though, let's add the <script> tag to our examples/default.vue file so that all the named data values are present.

Just place the following code right below the <template> tag and the comments!

<script>
/**
 * We've got to import our infinite scroll component! 
 */
import { InfiniteScroll } from 'infinite-scroll-component';

export default {
    /**
     * Registering the component will allow us to
     * use it in our template, as is shown above.
     */ 
    components: {
        InfiniteScroll
    },
    data() {
        return {
            /**
             * Here we've adding the values to that are
             * getting passed to the InfiniteScroll
             * comonent. They could be directly added in, 
             * the template, though are better organized
             * in the data method like this.
             */
            limit: 25,
            /**
             * Depending on the API, the returned records may be
             * nested in the response object. This key is optional
             * though can be used for accessing a nested list.
             */
            respKey: 'articlesList.items',
            /**
             * Optional auth token, depending on GraphQL API
             * REPLACE IT WITH YOUR API TOKEN
             */ 
            authToken: 'YOUR API TOKEN',
            /**
             * Required GraphQL API endpoint from where records get fetched.
             * REPLACE IT WITH YOUR WORKSPACE API ENDPOINT
             */
            endpoint: 'YOUR WORKSPACE API ENDPOINT',
            /**
             * Required GraphQL query for fetching records. This query
             * is designed for our 8base API and will return the paginated
             * results from our articles table.
             */
            query: `query($limit: Int, $skip: Int) {
                articlesList(first: $limit, skip: $skip) {
                    items {
                        id
                        title
                        body
                    }
                }
            }`
        }
    }
};
</script>

Nice work! Our examples/default.vue component is set up. Make sure that you updated the endpoint and apiToken values with those from your workspace.

`infiniteScroll.vue`

Now it's time for the actual InfiniteScroll component. Similarly to the last component, let's start with the <template> and <style> tags. Infinite scrolling does require some functional styling.

<style scoped>
/**
 * Some of the styling is functional, while other
 * is aesthetic. Feel free to play with it!
 */
section {
  overflow-y: scroll;
  height: 500px;
}
</style>

<template>
  <!-- 
    Component container with scroll event listener
    for triggering handle scroll event.
  -->
  <section @scroll="handleScroll">
    <!--
      For every item in the items array, render
      the slotted template and bind the item data.
     -->
    <slot v-for="item in items" v-bind="item" />
  </section>
</template>

<!-- 
  Next up... <script> will go here 
-->

I know. It's almost frustratingly simple, right? However, why make something more complex than it has to be? All we want to do is template every record fetched from our API, as well as know when to fetch more of them. That is what this does.

So, let's now add the <script> tag that will make everything actually work.

<script>
/* eslint-disable no-console */

/* Imports the graphQL request client */
import { GraphQLClient } from "graphql-request";

export default {
  /**
   * Declare the props expected to be passed from
   * any parent component (the ones in Dev.vue).
   */
  props: {
    query: {
      type: String,
      required: true
    },
    respKey: {
      type: String,
      default: ""
    },
    limit: {
      type: Number,
      default: 25
    },
    endpoint: {
      type: String,
      required: true
    },
    authToken: {
      type: String,
      default: ""
    }
  },
  data() {
    return {
      /* The array for storing all records fetched */
      items: [],
      /**
       * Configure the GraphQL Client, setting headers
       * only if the authTokenis specified.
       */
      client: new GraphQLClient(
        this.endpoint,
        this.authToken
          ? {
              headers: {
                authorization: `Bearer ${this.authToken}`
              }
            }
          : null
      )
    };
  },
  computed: {
      respKeyParser() {
          return this.respKey.split('.')
      }
  },
  methods: {
    /**
     * Callback for the onscroll event checks whether the scroll position
     * is near the bottom of the scroll container.
     */
    handleScroll({ target: { scrollTop, clientHeight, scrollHeight } }) {
      if (scrollTop + clientHeight >= scrollHeight) this.loadBatch();
    },
    /**
     * When a new batch of articles are retrieved from the API,
     * add them to the items.
     */
    handleLoad(response) {
      if (this.respKey) {
          response = this.respKeyParser.reduce((o, v) => o[v], response)
      }
      this.items = this.items.concat(response);
    },
    /**
     * Use the client to send query to GraphQL API
     * with the needed variables, 'limit' and 'skip'.
     */
    loadBatch() {
      this.client
        .request(this.query, {
          limit: this.limit,
          skip: this.items.length
        })
        .then(this.handleLoad)
        .catch(console.error);
    }
  },
  /**
   * When the component mounts (first renders), load the
   * initial batch of posts.
   */
  mounted() {
    this.loadBatch();
  }
};
</script>

Naturally, this part is a little bit meatier than the others. That said, there are really only several things worth pointing out; the in-code documentation should handle the rest.

First off, we initialize the GraphQLClient and conditionally pass it headers depending on whether or not an authToken was passed. The initialized client is what gets used in the loadBatch method to execute GraphQL calls to our API. It uses the required query prop, which receives the skip and limit variables.

The skip and limit variables are what the articlesList query requires to handle pagination. While limit simply represents how many records to load per request, skip specifies how many records have already been loaded – or from which index in the list to slice. Thus, if we initially fetch records A, B, and C from our API with limit = 3, skip = 0, and then on the following request specify limit = 3, skip = 3, we'll receive records D, E, and F.

Lastly, let's look at the handleScroll method. This is that callback method for the @scroll event. By unpacking the passed event argument we get access to the scrollTop, clientHeight, and scrollHeight values. The clientHeight is a fixed value that represents the height of the scrollable element in pixels. Meanwhile, scrollTop is changing on every scroll event to represent the distance from the top of the scroll container to the current position.

If the clientHeight plus scrollTop is greater than to or equal to the scrollHeight (the scrollable height of the element in pixels) then we know the container has been fully scrolled!

`index.js`

Wondering why your component isn't appearing in the browser (http://localhost:8080)? We didn't export it!

Update the index.js file with the following:

import InfiniteScroll from './infiniteScroll.vue';

export { InfiniteScroll }

Wrap up and some other fun stuff

Our pagination component is done! It can now be used with any Vue project with any GraphQL API. The component should be rendering out the records in the browser. If not, check out the errors and let me know if something is acting funky!

Additionally, if you're interested in building a full pagination component (tabs with navigation) as opposed to an infinite scroll. Check out this Pagination in Vue.js article by Denny Hendrick.

With that said, here is the tutorial's GitHub repository with examples

Localizing Image Text Overlays using Cloudinary + 8base

Seb Scholl — Sat, 07 Sep 2019 16:34:38 +0000

Imagine that you're a social media intern. Please, bear with me! You're a social media intern and your manager, instead of including you in on strategy meetings, hands you a laundry list of image-related tasks. It includes:

Crop this.
Brighten that.
Overlay "New arrivals!" on the Twitter header image.
Resize the Facebook share card.
Get me coffee.
Translate "New arrivals!" to Russian, German, and Swahili.

...You get the point

Now, you're a smart cookie. There's no way you want to spend your day wasting away on the computer having to MANUALLY manipulate all these images. So, you set out to find a better way.

⏸ Story over, for now

That scenario is no made-up story. It's real! Every day, whether at work or for personal projects, millions of images get created, edited, updated, hosted, taken down, lost, and so on. Services that help manage the chaos or streamline the process can be incredibly helpful.

The other day, a friend shared with me Cloudinary's URL API. Immediately, I saw it as being an answer to so many image-related inefficiencies suffered by companies and people. Very quickly, I'll mention a why and a how.

Why

From a single image, dozens of tweaked versions might need to get created (faded, text-overlay, black-white, etc.). Each of those versions takes time to create, update, and organize.

How

Cloudinary's URL API takes a dynamic parameter that applies transformations to the image upon retrieval. Think of it like on-demand Photoshop!

Personally, this got me excited. Notably, the Text Overlay transformation. After spending a little time playing with it, I wanted to see if it could be extended to incorporate localization (translation) of image text.

A working demo came out of the exercise. You can play with it here, or keep reading and learn how it works!

First off, let's take a quick look at the anatomy of the URL API. A large section of parameters exists between the upload/ and /horse.jpg sections. These are a list of image transformations that get executed when the image is requested. Pretty cool! Right? The documentation is right here if you'd like to dive deeper.

https://res.cloudinary.com/demo/image/upload/c_crop,g_face,ar_16:9,w_1200,h_600/e_auto_contrast/b_rgb:00000099,e_gradient_fade,y_-0.4/co_white,fl_relative,l_text:Times_100_bold_italic:I%20am%20a%20unicorn!,w_0.95/co_black,e_shadow,x_2,y_1/fl_layer_apply,g_south_west,x_20,y_25/dpr_auto,q_auto,f_auto/horse.jpg

Now, the image you see below gets rendered using the link above. Moreover, - this is the crucial part - if you change the transformation, a brand new image gets returned!

The l_text:Times_100_bold_italic:I%20am%20a%20unicorn! is easily visible when inspecting the URL. While we can't add a custom transformation tags (that is, on Cloudinary's side), we do have the ability to apply transformations to the URL. Meaning that, in the case of localizing our image overlays, we can coerce the URL before requesting the image.

A serverless GraphQL resolver function can get deployed to an 8base workspace to accomplish this. It can handle the parsing of the URL and translation. There are many ways to deploy a serverless function. However, 8base made it super simple and straight forward.

As a quick specification, let's design the function to behave as follows.

If a local_[2-char-lang-code] tag precedes the text, translate the text, and update the URL.
If a local code does not precede the text, return the original URL.

Enough talk, let's do it

1. Create a new 8base project

If you have an existing projected, you can always add a new function to it.

# Install the CLI globally
npm install -g 8base-cli

# Initialize a new project with a GraphQL resolver called "localizer."
8base init my-project --functions="resolver:localizer"

These commands create a new project with all the files and code we need to start invoking our GraphQL resolver function. We'll need to make a few changes though before it's translating our Cloudinary URL's 😉

2. Update the resolver's `graphql.schema`

Open up the file at src/resolvers/localizer/schema.graphql. We need to define our query operation and response. In this case, we'll be returning an object with the updated url after having received the cloudinaryUrl. Update the file with the following snippet.

type LocalizeResult {
  url: String!
}

extend type Query {
  localize(cloudinaryUrl: String!): LocalizeResult
}

3. Update the mock for `invoke-local`

Update src/resolvers/localizer/mocks/request.json so that the function can get invoked locally with data. The mock file generated has the same schema as what gets passed to the function in production.

{
  "data": {
    "cloudinaryUrl": "https://res.cloudinary.com/cdemo/image/upload/c_crop,g_face,ar_16:9,w_1200,h_600/e_auto_contrast/b_rgb:00000099,e_gradient_fade,y_-0.4/co_white,fl_relative,l_text:Times_100_bold_italic:local_es:Breaking%20news:%208base%20solves%20all%20your%20image%20related%20needs!,w_0.95/co_black,e_shadow,x_2,y_1/fl_layer_apply,g_south_west,x_20,y_25/dpr_auto,q_auto,f_auto/dosh1/img-0.jpg"
  },
  "headers": {
    "x-header-1": "header value"
  },
  "body": "{\"cloudinaryUrl\":\"https://res.cloudinary.com/cdemo/image/upload/c_crop,g_face,ar_16:9,w_1200,h_600/e_auto_contrast/b_rgb:00000099,e_gradient_fade,y_-0.4/co_white,fl_relative,l_text:Times_100_bold_italic:local_es:Breaking%20news:%208base%20solves%20all%20your%20image%20related%20needs!,w_0.95/co_black,e_shadow,x_2,y_1/fl_layer_apply,g_south_west,x_20,y_25/dpr_auto,q_auto,f_auto/dosh1/img-0.jpg\"}"
}

4. The function

We're going to need a translation engine. I chose AWS Translate, which offers 2-million free characters per month. Let's add the required library and config to the project.

# Install AWS SDK
npm install --save aws-sdk

Update src/resolvers/localizer/handler.ts

const AWS  = require('aws-sdk');

AWS.config.update({
    region: 'us-east-1', 
    credentials: {
      accessKeyId: process.env.AWS_IAM_SECRET_KEY, 
      secretAccessKey: process.env.AWS_IAM_ACCESS_KEY 
    }
});

const translate = new AWS.Translate({ apiVersion: '2017-07-01' });

/* Other code ... */

When developing locally, you'll need to set your AWS credentials as environment variables or static values. The example you see above is what works when the function gets deployed to 8base. Here's the documentation on accessing 8base environment variables.

Since we're using TypeScript, the function response needs a type. This type must match the structure and name of that added to the graphql.schema file. For our scenario, prepend the following to the function body.

type LocalizeResult = {
  data: {
    url: string
  }
};

The function body is pretty self-explanatory. Instead of describing it here and then showing it there, please read the inline comments for clarification on what's happening.

export default async (event: any, ctx: any) : Promise<LocalizeResult> => {
  /**
   * Regex Statement for matching our custom local_tag and preceeding text
   */
  const REG_EX = /(local_[a-z]{2})\:(.*?)([,\/])/g
  /**
   * Pull the given cloudinary url from our function arguments 
   */
  let url = event.data.cloudinaryUrl
  /**
   * Execute our Regex statement returning a match object
   */
  const matchObj = REG_EX.exec(url);
  /**
   * If a local tag is matched, we're in business! If not,
   * we're simply returning the passed url.
   */
  if (matchObj) {
    /**
     * Pull out the matched local and text values from
     * the matchObj array.
     */
    let local = matchObj[1], text  = matchObj[2];

    try {
      /**
       * Make the request to AWS Translate after decoding the given text
       * and slicing the last two characters from the local tag (e.g. local_es)
       */
      let request = translate.translateText({
        TargetLanguageCode: local.slice(-2),
        SourceLanguageCode: 'auto',
        Text: decodeURI(text)
      }).promise();

      let data = await request;
      /**
       * The ACTUAL cloudinary url will break if it has our custom tag. Plus, we
       * need to update the text with the translation! So, let's replace the previously
       * matched locale and text with our tranlsated text, that needs to be escaped.
       */
      url = url.replace(`${local}:${text}`, data.TranslatedText.replace(/[.,%\`\s]/g,'%20'))
    } 
    catch (err) {
      console.log(err, err.stack);
    }    
  } 
  /**
   * Return the final result.
   */
  return {
    data: {
      url
    }
  }
};

5. Run it!

Done! Let's prove it by invoking our function locally. The returned URL's text section translates to the locale specified language! Copy the link and throw it in a browser to see the magic.

8base invoke-local localize -p src/resolvers/localize/mocks/request.json
invoking...

Result:
{
  "data": {
    "localize": {
      "url": "https://res.cloudinary.com/demo/image/upload/c_crop,g_face,ar_16:9,w_1200,h_600/e_auto_contrast/b_rgb:00000099,e_gradient_fade,y_-0.4/co_white,fl_relative,l_text:Times_100_bold_italic:¡Soy%20un%20unicornio%20genial!,w_0.95/co_black,e_shadow,x_2,y_1/fl_layer_apply,g_south_west,x_20,y_25/dpr_auto,q_auto,f_auto/horse.jpg"
    }
  }
}

🏁 Wrap up

Sorry, we're going back to storytime. Remember back when you were a social media intern? Well, you ended up finding and using Cloudinary for all your on-the-fly image transformation and 8base for lightening fast serverless deployment of serverless GraphQL functions.

Excited by the chance to become "Employee of the Month", you approach your boss and share with him the big news by saying:

"I was able to apply dynamic URL transformations to our images using a URL API and extend its functionality to support real-time translations of text overlay!"

Seemingly confused, your manager looks at your hands and responds:

"You forgot my coffee?"

Cloudinary and 8base both do A LOT more than what is in this post. I highly recommend you check them out!

Adding Code Blocks in Webflow CMS with Language Highlighting

Seb Scholl — Thu, 29 Aug 2019 16:47:10 +0000

Very recently the team at 8base decided to migrate our blog from Medium to Webflow. If a bag-of-words analysis were run on transcripts from conversations we had around why to do this, the primary representation would encompass SEO and related jargon. Nevertheless, our lead designer has since poured many hours into building a beautiful new blog on Webflow - as well as migrated every post over to their CMS.
‍
Only once all the work was done did we realize that Webflow CMS has no support for code blocks 🤦‍
‍
This wasn't trivial for us. As we're gearing up for the launch our new 8base Tutorials project (coming soon!) and often publishing blogs that demonstrate - with code - all the awesome things you can do on 8base, displaying properly formatted code both in-line and as blocks is a must.

Hopefully, Webflow is going to give some special attention to the CMS after its latest and most significant round of funding. Every other aspect of their product either flirts with or embodies awesomeness. So why would we anticipate anything less for the CMS?
‍
That said, we had to come up with another solution in the meantime. Moreover, as is the case with most problems, they're rarely unique to the person experiencing them! A quick search on the interwebs, and you'll find a blog post on daily detailing the same problem and proposing a solution.

With all due respect deserved to the author, his solution wasn't one we felt comfortable using.
‍

def publish(solution = "our own!")
    puts "So, we came up with #{solution}"
end

Defining Custom Tags

I'll keep this explanation short and sweet, in the spirit of the solution itself!
‍
Firstly, we defined two simple custom tags. The tags are an ERB + HTML style mash-up that allows for the easy denotation for when a code example starts and ends. Originally, we attempted at using HTML style tags (<>). However, they were being escaped and just led to a messier script.
‍

In-line Code

{% c-line %}shell command --options-maybe{% c-line-end %}.
‍

Code blocks

{% c-block language="js" %}
function logMessage(msg) {
    var preText = "New Message: "
    console.log(preText+msg)
}

logMessage("Multi-line code blocks are important.")
{% c-line-end %}

Adding Highlight.js

Many solutions advised using Prism for syntax highlighting. Reading through their docs, it just felt like overkill. So instead, we landed on Highlight.js. What's great about Highlight is that it allows you to style code to reflect a preferred text editor theme easily. Meaning that if you're a fan of Sublime Text 3 or Atom, code samples can be highlighted using editor themes.

So, we added the following inside our Blog Post Template <head>...</head> tag. The script tag loads the Highlight.js library and the first link tag imports syntax highlighted CSS styling for all supported languages while the second one imports the Atom One Light editor theme.
‍

<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.15.9/highlight.min.js"></script>
<link rel="stylesheet" type="text/css" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.15.9/languages/css.min.js">
<link rel="stylesheet" type="text/css" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.15.9/styles/atom-one-light.min.css">

Writing the Script

By default, Webflow requires jQuery and makes it available globally. This allows us to use it in any custom script that we choose to add to our page templates. Naturally, the same thing could be accomplished using Vanilla JS. However, using jQuery felt just a bit tidier.
‍

/* Run when the page has loaded */
$(document).ready(function(event) {
  /* This formats all the inline code examples. */
  $('p:contains("c-line"), li:contains("c-line")').each(function(index, el) {
    $(el).html(el.innerText.replace(
      /{\%\s*c-line\s*\%}(.*?){\%\s*c-line-end\s*\%}/gi,
      '<code class="inline-code">$1</code>'
    ))
  })

  /* This formats all the code block examples. */
  $('p:contains("c-block"), li:contains("c-block")').each(function(index, el) {
    $(el).html(el.innerHTML.replace(
/{\%\s*c-block\s*language=[\"|\'](.+)[\"|\']\s*\%}(.*?)\{\%\s*c-block-end\s*\%}/gi,
      "<pre><code class=\"$1\">$2</code></pre>"
    ))
  })

  /* Run Highlight JS on every code block */
  $('pre code').each(function(index, codeBlock) {
    /* Remove first child <br> */
    codeBlock.removeChild(codeBlock.childNodes[0])
    hljs.highlightBlock(codeBlock)
  })
});

‍
So, there are a couple of important things worth noting.
‍

The script executes on the $(document).ready() event.
The $("HTML_TAG:contains('CODE_TAG')") selectors return all DOM elements that contain the specified tag.
The Regex statement(s) match the custom opening and closing tags with proper HTML tags and preserve the language attribute - for the block - and all inner text.
Once the DOM is updated, the resulting code blocks are highlighted using the Highlight.js hljs.highlightBlock() function. ‍ We decided to forgo using syntax highlighting on the in-line examples. Instead, we added a custom inline-code class to the template that's independently styled. Additionally, we didn't like the extra space (<br> tag) that gets added to every code block. This is why we added the codeBlock.removeChild(block.childNodes[0]) line.

In Summary

As soon as Webflow updates their CMS to support either Markdown or native code blocks, we'll likely scrap this solution that we just shared. That said, we're pretty happy with what we came up with for its the readability and maintainability!
‍
Feel welcome to use this strategy yourself and let us know how it works.
‍
‍
‍
‍