DEV Community: Milecia

Build a Non-Profit App with Next.js and Cosmic

Milecia — Tue, 12 Apr 2022 19:39:40 +0000

There are a number of local and global issues happening right now and most of the time it feels like there's not much we can do to help. But there's always something we can do!

That's why we're going to build a simple non-profit app that will show off potential students and their stories and it will allow anyone who wants to donate to do so using Stripe. By the time you finish this tutorial, you'll have a basic template for a student-donor website that uses modern tools to build quickly and scale easily.

Tools we’ll be using

To build this app, we’re going to use the following technologies:

Next.js - A React framework that makes it easy to spin up a full-stack application.
Cosmic - A headless CMS that gives us the ability to manage our student and donation data quickly.
Stripe - A payment system that will allow us to accept donations.
Tailwind CSS - A style framework that lets us make responsive layouts.

TL;DR

Install the App Template

View the live demo

Check out the code

Making a Cosmic account

The first thing you'll need to set up is a free Cosmic account. Then you'll be prompted to create a new project. Make sure that you select the "Start from scratch" option. The name of the project is non-profit-cms, but feel free to call it anything you want. You can leave the bucket environment as "Production".

Next, we'll need to make a few object types for our donors and students. In the Cosmic dashboard, go to "Add Object Type". You'll see this screen.

Make sure you choose the "Multiple" object option. You only have to fill in the "Singular Name" with Donor and the other two fields auto-generate. Further down, we need to define the metafields in the "Content Model".

We'll have a few different fields for our donors: a student name, donation amount, the session id from Stripe, and optionally, a donor name and message. You should have the following metafields when you're done.

We'll add new donor objects every time a donation is made through Stripe and then we'll be able to show donations for each student once we start building the Next app. Before we get there, let's finish up the object types we'll need by adding another type called Student.

You'll go back to your Cosmic dashboard and create a "New Object Type". It will also have the "Multiple" type and this time the "Singular Name" will be Student. Once again, we need to create some metafields for this object type. So scroll down to the "Content Model" section and add these metafields: the student name, a major, a university, their story, and a headshot. Here's what all of the metafields should look like when you're finished.

Now when you get data for your students and donors, you should see something similar to this for the students in your dashboard.

And something similar to this for the donors in your dashboard.

That's all we need to get everything set up in Cosmic.

Getting some values for the Next app

Now that we have Cosmic configured as we need, let's get a few environment variables we'll need for the Next app we are about to build. Go to your Cosmic Dashboard and go to Bucket > Settings > API Access. This will give you the ability to access, read, and write to your Cosmic project. We'll be working with the students and donors so that we're able to maintain good records of who to send the proper student updates.

Before we make the Next project, there's one more service we need to get configured correctly. We need to have Stripe so that we can accept donations.

Setting up your Stripe account

You'll need to go to the Stripe site to create a free account. The main things you'll want to make sure of here are that your dashboard is left in test mode and that you add a "Public business name" in Settings > Account Details.

Now that your dashboard is configured, you can get the last two environment variables we'll need for the app. Go to [Developers > API keys](https://dashboard.stripe.com/test/apikeys) and get your Publishable key and Secret key.

With these values, we're ready to make this Next app.

Setting up the Next.js app

Lucky for us, there is a yarn command to generate a new Next app with the configs in place. That way we can just jump into writing code. To generate this project, run the following command in your terminal:

$ yarn create next-app --typescript

Then we can add the packages we'll be working with the following command:

$ yarn add cosmicjs tailwindcss stripe postcss @heroicons/react

There's just one last piece of setup we need to do before we can dive into the code.

Adding the .env file

Remember those values we grabbed from our Cosmic dashboard and our Stripe dashboard? We're going to add them to the project in a .env file. At the root of the project, add a new .env file. Inside that file, add the following values:

# .env
READ_KEY=your_cosmic_read_key
WRITE_KEY=your_cosmic_write_key
BUCKET_SLUG=your_cosmic_bucket_slug

STRIPE_SECRET_KEY=your_stripe_secret_key
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=your_stripe_publishable_key

With all of these values finally in place, we can get to the fun part of building the app.

Setting up Tailwind CSS

In order to take advantage of the Tailwind CSS package we install, there are a few configurations we need to add. There should be a tailwind.config.js file in the root of your project. Open that file and replace the existing code with the following.

// tailwind.config.js

module.exports = {
  content: [
    "./pages/**/*.{js,ts,jsx,tsx}",
    "./components/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    container: {
      center: true,
    },
    fontFamily: {
      "sans": ["Helvetica", "Arial", "sans-serif"],
    }
  },
  plugins: [],
}

Now take a look in the styles folder and you should see a global.css file. This is how we will enable TailwindCSS in our project. Open this file and replace the existing code with the following.

// global.css
@tailwind base;
@tailwind components;
@tailwind utilities;

That's all we need for our styles to work. Of course, you could write the CSS yourself, but sometimes it's just as good to go with an existing styles package.

A couple of utility components

Now that we can style the app, let's add a few components that will help tie the pages together. We're going to add a navigation bar so that we can get back to the home page all the time and there will be a branding footer so that you can always show the name of your organization. At the root of the project, add a new folder called components.

We'll start by making the navigation, so inside the components folder add a new file called Navigation.tsx. This will render a link back home. Add the following code to create this component.

// Navigation.tsx

import Link from 'next/link'
import { HomeIcon } from '@heroicons/react/solid'

export default function Navigation() {
  return (
    <header className="p-4 border-b-2">
      <Link passHref href={'/'}>
        <div className="flex hover:cursor-pointer gap-2">
          <HomeIcon className="h-6 w-6 text-blue-300" />
          <div>Home</div>
        </div>
      </Link>
    </header>
  )
}

The last little component we need to add is the footer. In the components folder, add a new file called Footer.tsx. This will render some text and an icon image at the bottom of each page. In this new file, add the following code.

// Footer.tsx

export default function Footer() {
  return (
    <footer className="p-4 border-t-2">
      <a
        href="https://www.cosmicjs.com?ref=non-profit-cms"
        target="_blank"
        rel="noopener noreferrer"
      >
        <div className="flex gap-2">
          <div>Powered by</div>
          {/* eslint-disable-next-line @next/next/no-img-element */}
          <img
            alt="Cosmic logo"
            src="https://cdn.cosmicjs.com/049dabb0-8e19-11ea-81c6-b3a804bfff46-cosmic-dark.png"
            width="100"
            height="100"
          />
        </div>
      </a>
    </footer>
  )
}

Those are the only two components that we needed to make. Now you'll need to update your _app.tsx file to include the Footer component. That way it will show on every page of the app. So open this file and update the existing component to match this:

// _app.tsx
...
import Footer from '../components/Footer'

function MyApp({ Component, pageProps }: AppProps) {
  return (
    <div className="flex flex-col h-screen justify-between">
      <Component {...pageProps} />
      <Footer />
    </div>
  )
}
...

Notice that there is a new import statement and that the whole app is now wrapped in a styled div that also contains that footer element. We're only adding the Navigation element to individual student pages, which we'll get to later.

Displaying all of the students

We can start working on the Next app to display all of the students to anyone who visits the website. We'll start by updating the existing index.tsx file to import and use Cosmic to pull in the student data. So add the following code right below the existing imports in the file.

// index.tsx
...
import Cosmic from 'cosmicjs'

const api = Cosmic()

const bucket = api.bucket({
  slug: process.env.BUCKET_SLUG,
  read_key: process.env.READ_KEY,
})
...

Then, we'll need to add the getStaticProps function to fetch the student data from Cosmic:

// index.tsx
...
export async function getStaticProps() {
  const query = {
    type: 'students',
  }
  const studentsReq = await bucket.getObjects({ query })
  const students: Student[] = studentsReq.objects

  return {
    props: {
      students,
    },
  }
}
...

This function only runs at build time for a page, so you won't be making a request each time. Inside this function, we're defining the query that we'll send in the Cosmic request. Then we make the request to the bucket we defined earlier and we get all of the student objects returned. Finally, we send the students array to the props of the page component.

Now that we have this data, we can render some elements to the home page. You can remove all of the current code that's inside the Home component and replace it with the following:

// index.tsx
...
const Home: NextPage = ({ students }) => {
  if (!students) {
    return <div>Loading our incredible students...</div>
  }

  return (
    <div>
      <Head>
        <title>Student Raiser</title>
        <meta
          name="description"
          content="A website dedicated to helping students receive the funding they need for college"
        />
        <link rel="icon" href="/favicon.ico" />
      </Head>

      <main>
        <h1 className="px-11 pt-11 text-2xl">Students in your area</h1>
        <div className="flex flex-wrap gap-4 p-11">
          {students.map((student: Student) => (
            <div
              className="hover:cursor-pointer w-64"
              key={student.metadata.name}
            >
              <Link
                passHref
                href={`/student/${encodeURIComponent(student.slug)}`}
              >
                <div
                  key={student.slug}
                  className="border-2 rounded max-w-sm rounded overflow-hidden shadow-lg"
                >
                  {/* eslint-disable-next-line @next/next/no-img-element */}
                  <img
                    src={`${student.metadata.student_headshot.imgix_url}?w=400`}
                    alt={student.metadata.name}
                    className="w-full"
                    style={{ backgroundPosition: 'cover' }}
                  />
                  <div className="p-4">
                    <div className="text-amber-800 p-1">
                      {student.metadata.name}
                    </div>
                    <div className="border-b-2 p-1">
                      {student.metadata.major}
                    </div>
                    <div className="p-1">{student.metadata.university}</div>
                  </div>
                </div>
              </Link>
            </div>
          ))}
        </div>
      </main>
    </div>
  )
}
...

It's mapping over the students array to create an element to highlight each student. Each of these elements can be clicked on to learn more about a particular student and that's the page we're going to work on now. We'll come back and add more styling, but if you run the app with yarn dev, you should see something similar to this.

Making a page for individual students

Now, we'll use Next's built-in dynamic routing to create pages for each student. Go ahead and add a new folder in the pages directory called student. Inside that folder, add a new file called [name].tsx.

Let's start by adding the imports we'll need to get this page working. At the top of the [name].tsx file, add the following lines.

// [name].tsx

import { useEffect, useState } from 'react'
import Cosmic from 'cosmicjs'
import { Donor, Student } from '../../types'
import Navigation from '../../components/Navigation'
import {
  BadgeCheckIcon,
  ExclamationIcon,
  UserCircleIcon,
  UserIcon,
} from '@heroicons/react/solid'
...

Don't worry about the types file yet. We'll be adding that shortly. For now, let's add a skeleton for the Student component below our imports.

// [name].tsx
...
function Student({ student, donors }) {
  return (
    <>
      <h2 className="container text-3xl py-8">{student.metadata.name}</h2>
    </>
  )
}

export default Student

We'll be adding a lot more to this component, but we have to get the student and donors data first. We'll use the getServerSideProps function to pull the data for a specific student from Cosmic each time this route is called. None of this is happening in the browser, so the data is still secure.

// [name].tsx
...
export async function getServerSideProps(context) {
  const slug = context.params.name

  const studentRes = await bucket.getObjects({
    props: 'metadata,id',
    query: {
      slug: slug,
      type: 'students',
    },
  })

  const student: Student = studentRes.objects[0]

  try {
    const donorsRes = await bucket.getObjects({
      props: 'metadata',
      query: {
        type: 'donors',
        'metadata.student': slug,
      },
    })

    let total

    const donors: Donor[] = donorsRes ? donorsRes.objects : null

    if (donors.length === 1) {
      total = donors[0].metadata.amount
    } else {
      total = donors
        .map((donor) => donor.metadata.amount)
        .reduce((prev, curr) => prev + curr, 0)
    }

    return {
      props: {
        student,
        donors,
        total,
      },
    }
  } catch {
    return {
      props: {
        student,
        donors: null,
        total: 0,
      },
    }
  }
}

Then we'll pass this data to the component to highlight a specific student to the users and potential donors. In the Student component, we're going to do a few things. First, we'll check to see if the student page has been accessed via a redirect from the Stripe checkout page. Then we'll display the student info we have stored in Cosmic. Next, we'll have a form for donors to fill out if they want to make a donation to this particular student. Finally, we'll have a list of all the donors for this particular student.

So you can replace the outline of the Student component with the following, complete code.

// [name].tsx
...
function Student({ student, donors, total }) {
  const [query, setQuery] = useState<string>('')

  useEffect(() => {
    // Check to see if this is a redirect back from Checkout
    const query = new URLSearchParams(window.location.search)

    if (query.get('success')) {
      setQuery('success')
      console.log('Donation made! You will receive an email confirmation.')
    }

    if (query.get('canceled')) {
      setQuery('canceled')
      console.log(
        'Donation canceled -- something weird happened but please try again.'
      )
    }
  }, [])

  return (
    <div>
      <Navigation />
      {query === 'success' && (
        <div
          className="bg-green-100 rounded-lg py-5 px-6 mb-3 text-base text-green-700 inline-flex items-center w-full"
          role="alert"
        >
          <BadgeCheckIcon className="w-4 h-4 mr-2 fill-current" />
          Donation made! You will receive an email confirmation.
        </div>
      )}
      {query === 'canceled' && (
        <div
          className="bg-yellow-100 rounded-lg py-5 px-6 mb-3 text-base text-yellow-700 inline-flex items-center w-full"
          role="alert"
        >
          <ExclamationIcon className="w-4 h-4 mr-2 fill-current" />
          Donation canceled -- something weird happened but please try again.
        </div>
      )}
      <h2 className="container text-3xl py-8">{student.metadata.name}</h2>
      <div className="container flex gap-4">
        <div>
          {/* eslint-disable-next-line @next/next/no-img-element */}
          <img
            src={`${student.metadata.student_headshot.imgix_url}?w=800`}
            alt={student.metadata.name}
            style={{ backgroundPosition: 'cover' }}
          />
          <div className="container border-y-2 my-4">
            <p className="font-bold pt-4 px-2">
              Major: {student.metadata.major}
            </p>
            <p className="font-bold border-b-2 pb-4 px-2">
              University: {student.metadata.university}
            </p>
            <p className="py-4 px-2">{student.metadata.story}</p>
          </div>
        </div>
        <div>
          <p className="font-bold text-xl pb-4">Total raised: ${total}</p>
          <form
            action="/api/donation"
            method="POST"
            className="bg-white shadow-md rounded px-8 pt-6 pb-8 mb-4"
          >
            <input name="student_id" type="hidden" value={student.id} />
            <div className="mb-4">
              <label
                className="block text-gray-700 text-sm font-bold mb-2"
                htmlFor="amount"
              >
                Donation Amount
              </label>
              <input
                className="shadow appearance-none border rounded w-full py-2 px-3 text-gray-700 leading-tight focus:outline-none focus:shadow-outline"
                name="amount"
                type="number"
                defaultValue={100}
              />
            </div>
            <div className="mb-4">
              <label className="block text-gray-700 text-sm font-bold mb-2">
                Name
              </label>
              <input
                className="shadow appearance-none border rounded w-full py-2 px-3 text-gray-700 mb-3 leading-tight focus:outline-none focus:shadow-outline"
                name="name"
                type="text"
                defaultValue="Anonymous"
              />
            </div>
            <div className="mb-6">
              <label className="block text-gray-700 text-sm font-bold mb-2">
                Message
              </label>
              <input
                className="shadow appearance-none border rounded w-full py-2 px-3 text-gray-700 mb-3 leading-tight focus:outline-none focus:shadow-outline"
                name="message"
                type="text"
                defaultValue="Good Luck!"
              />
            </div>
            <div>
              <button
                type="submit"
                role="link"
                className="hover:bg-lime-400 text-white font-bold py-2 px-4 border-b-12 border-lime-700 hover:border-lime-500 rounded-full text-lg bg-lime-500 w-64 mt-6 mx-8"
              >
                Make a Donation
              </button>
            </div>
          </form>
          <div className="flex flex-col gap-4 pt-4 w-full">
            {donors ? (
              donors.map((donor: Donor) => (
                <div
                  key={donor.slug}
                  className="border-b-2 rounded p-4 w-64 flex gap-4"
                >
                  <UserCircleIcon className="h-12 w-12 text-green-300" />
                  <div>
                    <p>{donor.metadata.name}</p>
                    <p>${donor.metadata.amount}</p>
                  </div>
                </div>
              ))
            ) : (
              <div className="border-2 rounded p-4 w-64 flex gap-4">
                <UserCircleIcon className="h-12 w-12 text-green-300" />
                <p>Be the first donor!</p>
              </div>
            )}
          </div>
        </div>
      </div>
      <div className="flex flex-col gap-4 p-11 w-full">
        <h2 className="text-xl font-bold">Encouragement</h2>
        {donors ? (
          donors.map((donor: Donor) => (
            <div
              key={donor.slug}
              className="flex flex-col border-b-2 rounded p-4 gap-4"
            >
              <div className="w-64 flex gap-4 w-full">
                <UserIcon className="h-12 w-12 text-green-300" />
                <div className="flex flex-col">
                  <p>{donor.metadata.name}</p>
                  <p>${donor.metadata.amount}</p>
                </div>
              </div>
              <p>{donor.metadata.message}</p>
            </div>
          ))
        ) : (
          <div>You can do it!</div>
        )}
      </div>
    </div>
  )
}
...

If you run the app now with yarn dev you should see something similar to this for one of the students.

Now that we've gotten all of the functionality filled out, let's go ahead and add that types.ts file so that we don't get any TypeScript errors.

Adding the types file

Having defined types for our data helps us know when APIs have changed and we won't get left with as many unexpected errors in production. At the root of your project, create a new file called types.ts and add the following code:

// types.ts

export interface Student {
  metadata: {
    name: string
    student_headshot: {
      url: string
      imgix_url: string
    }
    major: string
    university: string
    story: string
  }
  slug: string
}

export interface Donor {
  slug: string
  metadata: {
    name: string
    amount: number
    message: string
  }
}

This helps us define the data that we expect to use from our API calls to Cosmic.

Adding the Stripe checkout functionality

The last thing we need to add is the API that gets called with the donation form is submitted and we're going to use Stripe to handle this. If you look in the pages > api directory in your project, you'll see a file called hello.ts. You can delete this placeholder file and create a new file called donation.ts.

Let's open this new file and the following imports.

// donation.ts

import type { NextApiRequest, NextApiResponse } from 'next'
import Cosmic from 'cosmicjs'

const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY)

Since we only have to handle one POST request, our handler function can be relatively simple. We'll do a quick check to make sure a POST request is being made. If any other type of request is made, then we will throw an error.

After that request check, we'll make a try-catch statement that will first see if we can make a connection to our Cosmic bucket to add a new donor. After that, we make a checkout session with Stripe using the form information passed from the front-end. Then we get the session from Stripe to add their data to Cosmic.

Lastly, we create the metafield data to add a new donor to our Cosmic dashboard and use the addObject method to make sure this donor gets written to the correct object. Go ahead and add the following code to do all of this work.

// donation.ts
...
export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  if (req.method === 'POST') {
    try {
      const api = Cosmic()

      const bucket = api.bucket({
        slug: process.env.BUCKET_SLUG,
        read_key: process.env.READ_KEY,
        write_key: process.env.WRITE_KEY,
      })

      const { student_id, amount, name, message } = req.body

      const student = (
        await bucket.getObject({ id: student_id, props: 'id,title,slug' })
      ).object

      // Create Checkout Sessions from body params.
      const session = await stripe.checkout.sessions.create({
        line_items: [
          {
            amount: amount * 100, // Cents
            currency: 'usd',
            quantity: 1,
            name: `Donation - ${student.title}`,
          },
        ],
        mode: 'payment',
        success_url: `${req.headers.referer}/?success=true`,
        cancel_url: `${req.headers.referer}/?canceled=true`,
      })

      const donorParams = {
        title: name,
        type: 'donors',
        metafields: [
          {
            title: 'Name',
            type: 'text',
            value: name,
            key: 'name',
          },
          {
            title: 'Student',
            type: 'text',
            value: student.slug,
            key: 'student',
          },
          {
            title: 'Amount',
            type: 'number',
            value: Number(amount),
            key: 'amount',
          },
          {
            title: 'Message',
            type: 'text',
            value: message,
            key: 'message',
          },
          {
            title: 'Stripe Id',
            type: 'text',
            value: session.id,
            key: 'stripe_id',
          },
        ],
      }

      await bucket.addObject(donorParams)

      res.redirect(303, session.url)
    } catch (err) {
      res.status(err.statusCode || 500).json(err.message)
    }
  } else {
    res.setHeader('Allow', 'POST')
    res.status(405).end('Method Not Allowed')
  }
}

Finished code

You can find all of the code for this project in this repo.

Deploy this to Vercel

You can deploy this template to Vercel by clicking here.

Conclusion

Now you have a fully-integrated donation website that you can customize for any type of fundraiser-donor non-profit. Feel free to clone this and change the styles to match your own organization's needs.

Building an AR App with Markers

Milecia — Wed, 19 Jan 2022 14:22:55 +0000

Adding virtual things to the real world is something that's made a huge leap in popularity, especially with QR codes. With augmented reality (AR), we can take images in the real world and display digit things on top of them, kind of like the Nintendo DS used to do with those game cards.

In this tutorial, we'll make a browser-based AR app that displays interesting things on top of images. By the end of this, you'll know how to work with AR in a Redwood app.

Set up the Redwood app

We'll start by creating a new Redwood app. In a terminal, run the following command.

$ yarn create redwood-app ar-demo

This will generate a lot of files you can work with on both the front-end and back-end, but our focus will be on the front-end. You can find all of the code for the React front-end in the web directory.

There are a few libraries we'll need to add to our app in order to get the AR functionality we need and we'll be doing that in a slightly different way.

Add the libraries you need

There aren't a lot of pre-built JavaScript AR libraries out there and the ones available have their own unique set of challenges, but we'll use AR.js since many of the others are built on top of this.

You'll also find that JavaScript AR systems commonly use Three.js or A-frame to handle rendering objects. The app we're making is a little unique in that it's built around the browser. Most AR apps are built for use on mobile devices, but this is a way that all JavaScript developers can play with AR without needing mobile development knowledge.

The tricky part about working with AR in the browser is that the libraries we have available want to be in the <body> of the app, which is hard to do with any of the frameworks. So we'll start by adding the libraries we're working with to the <head> of our index.html file in the web > src directory.

<script src="https://aframe.io/releases/1.0.4/aframe.min.js"></script>
<!-- we import arjs version without NFT but with marker + location based support -->
<script src="https://raw.githack.com/AR-js-org/AR.js/master/aframe/build/aframe-ar.js"></script>

We're using the A-frame version of the AR.js library. Now that we have the libraries imported, let's add the elements we need inside the <body>.

Setting up the AR elements

This will feel odd to anyone who's been working in a framework because we typically don't add anything to the DOM like this. It's a quirk to this AR library because it requires the elements to be directly inside the <body>, not in a component. I did some digging trying to find ways to make this into a component and took a look at some other libraries, but couldn't find anything ready to use.

There are ways to componentize this, but it will take some time and craftiness! For now, it's important to see how this works so that you at least know how to work with AR.

So inside the <body>, add the following code.

<a-scene embedded arjs>
    <a-marker type="pattern" url="https://raw.githubusercontent.com/flippedcoder/blog-examples/main/clear-world/pattern-check.patt">
        <a-sphere radius="1" color="#EF2D5E"></a-sphere>
    </a-marker>
    <a-entity camera></a-entity>
</a-scene>

This gives you an AR environment that will let you detect when a certain picture is displayed in the camera. These pictures are called markers. So anytime you are running this app and you point to a marker, you'll get some kind of interaction in the browser.

Since we're using A-frame, that interaction could be any number of things from a simple object being displayed on top of the marker to an entire game being created on top of the marker. You can have a lot of fun playing around with A-frame and what you want to display on your marker.

There are a few things to note in the code. Everything is contained within the <a-scence> which is an A-frame tag that creates the virtual environment. The <a-marker> tag is how we enable AR functionality in the app. We tell the app to look for an image that has a pattern type and give it an absolute link to the pattern file.

Whenever the correct marker image is found and it matches the pattern we have, then the <a-sphere> is displayed on top of the marker. Anything that you build inside of the <a-marker> tag will display on top of the marker image so feel free to get more creative!

Lastly, we have the <a-camera> tag. This is what opens the webcam or the camera on your phone so that you can target the marker image in real life.

That's actually all for the code part! Now we need to make a marker image. There's a tool available that lets us do that easily.

Make a marker image

To make a marker image and the associated pattern file, go to this site: https://jeromeetienne.github.io/AR.js/three.js/examples/marker-training/examples/generator.html. You can upload an image of your choosing, but keep in mind that there needs to be high contrast between the background and foreground and simple images work the best. You can also use the example image that's displayed.

You'll need to download the image and the marker. The marker is your pattern file and the image is the file that you will point your camera at. When you have the marker file, you can upload it to your own GitHub repo and replace the link in the code above.

Now that you have your marker file and the image ready, we can start the app and see what this looks like!

Running the AR app

In a terminal, run the following command.

$ yarn redwood dev

This will start up the Redwood app and you should see something like this in your browser.

Now if you open the image on your mobile device, you should see a pink ball on top of it in the browser.

Now you're working with AR directly in your browser and if you scroll down the page you'll see the rest of the app at the bottom. This is super useful if the AR portion of your app is just a small part of what a user needs.

Finished code

You can check out the full code in the clear-world folder of this repo or you can take a look in this Code Sandbox.

Conclusion

Adding AR to the web is actually still a pretty tricky thing to do considering most libraries have been built around the mobile experience. There's still a lot of room to grow and create web-based AR apps for people projects that might need more than just the AR interface and they need a full-stack web app supporting it.

Creating an Asteroid Map with a NASA API

Milecia — Tue, 11 Jan 2022 15:25:24 +0000

There are a lot of cool APIs out there that let you work with interesting datasets. If you are interested in space at all, then the NASA APIs might be something you want to check out.

In this post, we'll use one of the NASA APIs to create an asteroid map. This will give us a representation of how many asteroids came close to hitting the Earth and how big they were. We'll save these images to Cloudinary so we can review them later.

Initial setup

There are a few things we need to have in place before starting on the code. First, you'll need an API key for the NASA Asteroids - NeoWs API we'll be using. You can get a free one here. It'll send the API key to the email you enter.

Next, you'll need a Cloudinary account to store the asteroid map images that you can reference later. You can sign up for a free account here.

We'll be working with a local Postgres database, so if you don't have that installed, you can download it here.

Now that we have all of these things set up, we can start working on the app.

Generate a new Redwood project

In a terminal, run the following command:

$ yarn create redwood-app asteroid-map

This will create a lot of new files and directories for you. Our focus will be in the web and api folders. The web folder is where we'll write all fo the front-end code in React. The api folder is where we'll handle the Postgres connection and the GraphQL back-end.

Create the database schema and connection

We'll start by connecting to the database and setting up our schema. First, open the .env file in the root of the project. You'll see a commented-out line that defines the DATABASE_URL. Uncomment that line and update it to match your local connection string. That might look similar to this:

DATABASE_URL=postgres://postgres:admin@localhost:5432/asteroids

You won't need to create a new database manually. When we run the first migration, the asteroids database will be created for you.

Now we can write the schema for the database. In the api > db folder, open schema.prisma. Redwood uses Prisma to handle the database operations. This file is where we use the connection string and write the schema for all of our tables.

Update the provider value from sqlite to postgresql. This tells Primsa we're working with a Postgres instance. You can see where the connection string is being read from the DATABASE_URL value we set earlier.

Next, you can delete the example model and replace it with the following:

model Map {
  id        Int    @id @default(autoincrement())
  name      String
  startDate DateTime
  endDate   DateTime
  mapUrl    String
}

This model represents the data we'll store in the database. The NASA API returns asteroid information based on the dates we submit, so we're storing those to know which dates correspond to the asteroid maps.

Running a database migration

Since we have the schema in place for the table we'll save the asteroid maps to, let's go ahead and run a database migration. In your terminal, run the following command:

$ yarn redwood prisma migrate dev

This will create the database (if needed) and then add the Map table to it.

Make the GraphQL types and resolvers

That's all we need to do on the database side of this app. Now we can turn to the GraphQL server. Redwood's CLI has a lot of commands that do some heavy lifting for us. We're going to generate the types and resolvers for our back-end with this command:

$ yarn redwood generate sdl --crud map

This will generate several files for us that handle all of the CRUD functionality for our maps. The only things we need to add are the types for the data we get from the NASA API and a resolver to fetch that data.

Adding the asteroid data types

In the api > src > graphql directory, open the newly generated maps.sdl.ts file. This already has the type definitions for the CRUD queries and mutations we might use to update the database.

Now we'll add the type to define the data we'll get from the API, the input type to send to the API, and the query we can use to return the data. Right below the Map type, add this code:

type Asteroid {
  missDistance: String
  estimatedDiameter: String
}

input AsteroidInput {
  startDate: Date!
  endDate: Date!
  viewDate: Date!
}

type Query {
  asteroids(input: AsteroidInput): [Asteroid] @requireAuth
  maps: [Map!]! @requireAuth
  map(id: Int!): Map @requireAuth
}

That will give us access to the query and what it needs. Let's go define the resolver to fetch this data.

Calling the NASA API through a resolver

This is one of the cool things about GraphQL. You can call another API in a resolver and the data gets sent through the same endpoint as if it were hitting your own database.

In api > src > services > maps, open the maps.js file. This has the CRUD resolvers created from that CLI command we ran earlier. Below all of these, add the following resolver to fetch the asteroid data:

export const asteroids = ({ input }) => {
  return fetch(`https://api.nasa.gov/neo/rest/v1/feed?start_date=${input.startDate.toISOString().split('T')[0]}&end_date=${input.endDate.toISOString().split('T')[0]}&api_key=${your_api_key_really_goes_here}`)
  .then(response => {
    return response.json()
  })
  .then(rawData => {
    const data = rawData.near_earth_objects[input.viewDate.toISOString().split('T')[0]]

    const asteroids = data.map(value => {
      return {
        missDistance: value.close_approach_data[0].miss_distance.kilometers,
        estimatedDiameter: value.estimated_diameter.kilometers.estimated_diameter_max
      }
    })

    return asteroids
  })
}

This resolver takes the input we pass to it and makes this request to the API. Like with many API requests, we have to send the inputs in a particular format. That's why we're splitting the date string the way we are. GraphQL passes the date in a format the NASA API doesn't like.

Then we get the data from the response and check out the asteroids that were close by on the viewDate we pass in. This date can be any time between the start and end dates. We take the data returned from the API and extract the values we need and that's what we pass in a successful response.

That's everything for the back-end! We have all of the types and resolvers we need to get the asteroid data and save things to the database. We can turn our attention to the front-end where we'll wrap things up.

Building the user interface

Let's jump right in. There's one package that we need to install in order to save the asteroid maps we create. In your terminal, go to the web directory and run:

$ yarn add html-to-image

This will allow us to capture an image of the asteroid map really quickly.

We can use the Redwood CLI to generate the asteroid map page for us. So in your terminal go back to the root of the project and run the following command:

$ yarn redwood generate page asteroid

This will update the Routes.tsx file to have this new path and it generates a few files for us in web > src > pages > AsteroidPage. The file we will work in is AsteroidPage.tsx. Open this file and delete all of the existing import statements and replace them with these:

import { useQuery, useMutation } from '@redwoodjs/web'
import { useState, useRef } from 'react'
import { toPng } from 'html-to-image'

After these imports, we can add the GraphQL query to get our asteroid data and the mutation to save the map to the Cloudinary and the database.

const CREATE_MAP_MUTATION = gql`
  mutation CreateMapMutation($input: CreateMapInput!) {
    createMap(input: $input) {
      id
    }
  }
`

const GET_ASTEROIDS = gql`
  query GetAsteroids($input: AsteroidInput!) {
    asteroids(input: $input) {
      missDistance
      estimatedDiameter
    }
  }
`

Adding states and using hooks in the component

With all of the imports and GraphQL definitions in place, let's start working inside the AsteroidPage component. You can delete everything out of the component because we'll be writing a lot of different code.

We'll start by adding the states and other hooks we need for the component.

const [createMap] = useMutation(CREATE_MAP_MUTATION)

const canvasRef = useRef(null)

const [startDate, setStartDate] = useState("2021-08-12")
const [endDate, setEndDate] = useState("2021-08-15")
const [viewDate, setViewDate] = useState("2021-08-13")

const { loading, data } = useQuery(GET_ASTEROIDS, {
  variables: { input: { startDate: startDate, endDate: endDate, viewDate: viewDate }},
})

First, we create the method that does the mutation to add new records to the database. Then we set the canvas ref that will hold the image of the asteroid map. Next, we set a few different date states. These will let us adjust what's in the map we save and what we see in the app.

Then there's the data fetch query. This calls that resolver we made to get the asteroid data from the NASA API. We pass in the input in the shape we defined in the types on the back-end. These values come from the states, so whenever the state values change we can get a new asteroid map.

Having a loading state

You'll notice that we have a loading value from the useQuery call. This tells us if the data is still being fetched. It's important to have some kind of element that tells the user a page is loading. This also prevents the app from crashing when the data isn't available yet. So below the data query, add this code:

if (loading) {
  return <div>Loading...</div>
}

This just renders a loading message on the page.

The elements that get rendered

Now that we have the data coming in, let's write the return statement for what should render on the page. Below the loading state check, add the following code and we'll go through it:

return (
  <>
    <h1>AsteroidPage</h1>
    <form onSubmit={submit}>
      <div>
        <label htmlFor="mapName">Map Name</label>
        <input type="text" name="mapName" />
      </div>
      <div>
        <label htmlFor="startDate">Start Date</label>
        <input type="date" name="startDate" />
      </div>
      <div>
        <label htmlFor="endDate">End Date</label>
        <input type="date" name="endDate" />
      </div>
      <div>
        <label htmlFor="viewDate">View Date</label>
        <input type="date" name="viewDate" />
      </div>
      <button type="submit">Save Asteroid Map</button>
    </form>
    <button type="button" onClick={makeAsteroidMap}>View Map</button>
    <canvas id="asteroidMap" ref={canvasRef} height="3000" width="3000"></canvas>
  </>
)

There's not as much going on as it might seem. We have a form that has a few input elements for the name we want to give an asteroid map and the dates we need to get the data and image. This form has a submit button that fetches new asteroid data based on our inputs and saves a new map.

There's another button that lets us view the asteroid map in the canvas element below it. The canvas element is what we target in the useRef hook above. The form and view map buttons have functions that we need to write.

If you want to look at the app so far, run yarn redwood dev in your terminal. You should see something like this.

The submit function

We'll add this function right below the loading state check. This will get the form data, update the date states, take a snapshot of the asteroid map in the canvas, upload it to Cloudinary, and then make a new database record.

async function submit(e) {
  e.preventDefault()
  const mapName = e.currentTarget.mapName.value
  const startDate = e.currentTarget.startDate.value
  const endDate = e.currentTarget.endDate.value
  const viewDate = e.currentTarget.viewDate.value

  setStartDate(startDate)
  setEndDate(endDate)
  setViewDate(viewDate)

  if (canvasRef.current === null) {
    return
  }

  const dataUrl = await toPng(canvasRef.current, { cacheBust: true })

  const uploadApi = `https://api.cloudinary.com/v1_1/${cloudName}/image/upload`

  const formData = new FormData()
  formData.append('file', dataUrl)
  formData.append('upload_preset', upload_preset_value)

  const cloudinaryRes = await fetch(uploadApi, {
    method: 'POST',
    body: formData,
  })

  const input = {
    name: mapName,
    startDate: new Date(startDate),
    endDate: new Date(endDate),
    mapUrl: cloudinaryRes.url
  }

  createMap({
    variables: { input },
  })
}

You'll need to get your cloudName and upload preset value from your Cloudinary console. The only function left to write is the one to draw the asteroid map on the canvas.

Drawing the asteroid map

This will create a different sized circle at various distances from the left side of the page to show how close they were to Earth and how big they were.

function makeAsteroidMap() {
  if (canvasRef.current.getContext) {
    let ctx = canvasRef.current.getContext('2d')

    data.asteroids.forEach((asteroid) => {
      const scaledDistance = asteroid.missDistance / 75000
      const scaledSize = asteroid.estimatedDiameter * 100
      let circle = new Path2D()

      circle.arc(scaledDistance * 2, scaledDistance, scaledSize, 0, 2 * Math.PI)

      ctx.fill(circle)
    })
  }
}

The scaling here isn't based on anything in particular, so feel free to play around with the math!

Now if you run the app and click the View Map button, you'll see something like this.

If you update the dates, you can view a different map and save it to the database. That's all of the code for this app!

Now you can see how close we almost came to an asteroid event every day.

Finished code

You can take a look at the complete project in the asteroid-map folder of this repo. Or you can take a look at the front-end in this Code Sandbox. You'll have to update some values to match yours in order for this to work.

Conclusion

Working with external APIs is something we commonly do and GraphQL is one of the ways we can centralize all of the APIs we call. Using this as a tool to make visual representations of how close we came to being hit by asteroids every day is just a fun way to use that functionality.

Make A Custom Map App with Redwood

Milecia — Tue, 30 Nov 2021 14:31:48 +0000

Having locations marked on a map is something that a lot of us depend on. Whether it's figuring out where a restaurant is or trying to find the nearest metro, we use maps quite a bit. Knowing how to work with maps as a developer is a niche skill with plenty of demand.

In this tutorial, we'll make a map app that lets users choose the location for the pin. It will save this location and upload a snapshot of the map to Cloudinary.

Some initial things

There are a couple of tools we need to set up before we start writing any code. We'll be using a local PostgreSQL database. If you don't have a local instance installed, you can download it for free here.

You'll also need a Cloudinary account to host your map snapshots. You can sign up for a free one here. Since we'll be uploading images from the front-end directly to Cloudinary, we need to set up an upload preset in our account settings. On this page, click the "Add upload preset" button.

This will bring us to a new page where we can define specific values for our preset. There are only a couple of things we'll change here.

Update the "Signing Mode" to "Unsigned". This is how we'll handle the uploads from our client app. Then add a "Folder" value of "map-shots". This will put all of our uploaded map snapshots into one folder. Your settings should look similar to this.

Take a quick note of the "Upload preset name". You'll need this when it's time to upload images from the user. Now we can write some code.

Creating the app

We're going to make this app using Redwood. Open a terminal and run the following command.

yarn create redwood-app map-shot

This creates a new Redwood app that has a fully functioning React front-end and GraphQL back-end. The front-end code is stored in the web directory and the back-end code is in the api directory. These are the two main folders we'll be working with.

Let's start by setting up a quick environment variable. You should have a .env file at the root of your project. Open that and add the connection string for your local Postgres instance. That might look something like this.

DATABASE_URL=postgres://admin:postgres@localhost:5432/map_shots

Now we can start writing the schema for our database.

Defining the database schema

In api > db, open the schema.prisma file. This is where we define our database connection and table schema using Prisma. We first need to update the provider value to postgresql from sqlite. We set the DATABASE_URL value in the .env file so that's ready for us.

Now we can delete the example model and replace it with a schema for our map snapshots. Add the following code to replace the example model.

model Snapshot {
  id        String @id @default(uuid())
  name      String
  xPosition Float
  yPosition Float
  imageUrl  String
}

These are the values that will be taken from the user and stored in our database. This is the only table we'll have for now so we can save these changes and run a database migration to persist them to Postgres. To do that, open your terminal and run:

yarn rw prisma migrate dev

This will create the new database and this table we've defined. With all of this in place, we're done with the database work. Let's turn our attention to the GraphQL server.

Generating the GraphQL server

One of the best things about working with Redwood is how much work it does for you. We need to define the types and resolvers to make updates to the rows in our database. Normally we would make those files and write the code ourselves, but there's a command in Redwood that does this for us based on the schema we just wrote.

In your terminal, run the following command:

yarn rw g sdl snapshot --crud

Now take a look in the api > src directory. You'll see some updates to the graphql and services directories. The command we just ran generated both the GraphQL types and all of the CRUD mutations and queries for us.

Take a look at api > src > graphql > snapshots.sdl.js to see the types. Then look through api > src > services > snapshots to see the queries, mutations, and test files that have been created for us.

We just created our entire GraphQL server with one command. You can modify any of the code in these files if you ever need more complex types or resolvers, but this gives you a way to quickly set up the basics.

Since we have the back-end ready to go, let's switch over to the front-end and set things up for our users to interact with.

Making the user interface

We'll need to add three packages in order to make our map. In a terminal, go to the web directory and run the following:

yarn add leaflet react-leaflet html-to-image

This will give us access to react-leaflet which lets us do a lot of cool things with maps.

We need to use leaflet's stylesheet so that the map components render correctly. That means we need to add this code to index.html inside the <head>.

<link rel="stylesheet" href="https://unpkg.com/leaflet@1.7.1/dist/leaflet.css" integrity="sha512-xodZBNTC5n17Xt2atTPuE1HxjVMSvLVW9ocqUKLsCC5CXdbqCmblAshOMAS6/keqq/sMZMZ19scR4PsZChSR7A=="
crossorigin="" />

With this package installed and configured, we can start working on the page for this map.

Add a new page

We'll use another Redwood command to generate the page and route for where the map will be rendered. In a terminal go to the root of your project and run this:

yarn rw g page map

If you go to web > src > pages, you'll see a newly created folder called MapPage. This has several files to help enforce coding best practices, but the main one we'll work with is MapPage.js.

Add the core functionality to the page

We can delete all of the imports and clear out the code in the component to start fresh. Then we'll add the following packages we'll be using.

import { useMutation } from '@redwoodjs/web'
import { useCallback, useRef, useState } from 'react'
import { MapContainer, TileLayer, Marker, Popup } from 'react-leaflet'
import { toPng } from 'html-to-image'

These are all of the methods and components we need to make this map app stored values in the database and images in Cloudinary.

Next we'll define the GraphQL mutation we need to add a new snapshot to the database. Right below the imports, add the following code:

const CREATE_SNAPSHOT_MUTATION = gql`
  mutation CreateSnapshotMutation($input: CreateSnapshotInput!) {
    createSnapshot(input: $input) {
      id
    }
  }
`

Now we need to start adding functionality inside the MapPage component. We'll start by setting up some variables. Your component should look like this:

const MapPage = () => {
  const mapRef = useRef(null)
  const [createSnapshot] = useMutation(CREATE_SNAPSHOT_MUTATION)
  const [position, setPosition] = useState([36.49, -100])
  const [name, setName] = useState('The pit of the Midwest')
}

We can write one of the functions that will let us handle our user changes. First, we'll write the function that will get called when a user submits the form we create a bit later. This will handle setting some states and it will call the method that uploads the image and adds the record to the database.

Below the initial variables, add the following function:

const updatePin = (e) => {
  e.preventDefault()

  const { xPosition, yPosition, name } = e.target.elements

  setPosition([xPosition.value, yPosition.value])
  setName(name.value)

  onCapture()
}

This is going to handle the event from our form submission so that the page doesn't refresh. It gets the form values from the inputs and then updates the respective states. Then it calls the onCapture method, which is where some interesting things happen.

Save a snapshot of the map to Cloudinary and the database

Let's go ahead and make this onCapture method. Add the following code to your component:

const onCapture = useCallback(async () => {
  if (mapRef.current === null) {
    return
  }

  const dataUrl = await toPng(mapRef.current, { cacheBust: true })

  const uploadApi = `https://api.cloudinary.com/v1_1/${cloudName}/image/upload`

  const formData = new FormData()
  formData.append('file', dataUrl)
  formData.append('upload_preset', uploadPresetName)

  const res = await fetch(uploadApi, {
    method: 'POST',
    body: formData,
  })

  const result = await res.json()

  const input = {
    name: name,
    xPosition: Number(position[0]),
    yPosition: Number(position[1]),
    imageUrl: result.url,
  }

  createSnapshot({
    variables: { input },
  })
}, [mapRef])

Quite a few things are happening here. First, we're checking to make sure our referenced component is loaded. Then we're using the toPng method from html-to-image to create a png data URL based on the elements inside our mapRef.

Next, add the API string for Cloudinary. This is where you'll need to use the cloud name from your account. Then we create a new FormData variable and add the data URL for the snapshot and the upload preset we created earlier.

Then we do a POST request to the API and upload the snapshot. We wait for the response to come back because it will have a Cloudinary URL we can use as the source for images in HTML elements. This is what we'll be saving to the database.

The last thing we do is make an input variable for our GraphQL call and then add this record to the database. All that's left is to write the elements that need to show to the user.

Adding the elements to the page

We need a return statement to render these elements. So add this code to your file and we'll talk through what's happening.

return (
  <div style={{ display: 'flex' }}>
    <div ref={mapRef}>
      <h1>{name}</h1>
      <MapContainer
        center={position}
        zoom={7}
        scrollWheelZoom={false}
        style={{ height: '550px', width: '750px' }}
      >
        <TileLayer
          attribution='&copy; <a href="http://osm.org/copyright">OpenStreetMap</a> contributors'
          url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"
        />
        <Marker position={position}>
          <Popup>The armpit of Oklahoma.</Popup>.
        </Marker>
      </MapContainer>
    </div>
    <form onSubmit={updatePin}>
      <div>
        <label for="name">Change map name</label>
        <input type="text" name="name" />
      </div>
      <div>
        <label for="xPosition">Change pin x-position</label>
        <input type="number" name="xPosition" />
      </div>
      <div>
        <label for="yPosition">Change pin y-position</label>
        <input type="number" name="yPosition" />
      </div>
      <button type="submit">Update</button>
    </form>
  </div>
)

We have a containing element with a flex style applied. This will show the map on the left of the screen and the form to its right. Then we'll have the container with our ref prop to capture the screenshot.

Inside of this, we have a title for the map and the map itself. The <MapContainer> component has a few props defined that tell the map where to be centered when a user first views the page.

In the <MapContainer> component, the <TileLayer> component is used to make up the map sections. You can check out the react-leaflet documentation for more information. The <Marker> component lets us set the little pinpoint you see on most maps.

Lastly, we have the <form> that calls the updatePin method whenever it is submitted. This is what triggers all of the functionality we wrote out earlier.

It's time to run the app and see all of this in action. At the root of your project, run this in the terminal:

yarn rw dev

This starts up the local development server for both the GraphQL server and the front-end. When the app opens in the browser, you should see something that looks like this:

Now you can update the map with the fields to the right. Keep in mind that the map won't auto-focus on the new point, so you might need to zoom out to see where you land. Here's an example of an update.

If you take a look at your Postgres instance, you'll see new records in your table and if you look on Cloudinary you'll see a new "map-shots" folder.

That's it! We're finally finished with the project.

Finished code

If you want to take a look at the complete code, check out the map-shot folder of this repo.

You can check out the front-end in this Code Sandbox.

Conclusion

You can expand this app to do many interesting things like making paths to special locations or pointing out obscure landmarks. One of the tricky things is making sure you stay on land! Hopefully, you see how you can bring together a lot of different technologies quickly to make a sophisticated app.

Making a User Interface for DApps in Redwood

Milecia — Mon, 15 Nov 2021 22:10:35 +0000

As much of a buzz term as blockchain has become, it's still a great technology. To take some of the magic out of it, blockchain is essentially a distributed database. A blockchain is made of blocks that contain data and those blocks are chained together across multiple machines, which make up the distributed network.

In this article, we'll build a distributed app in the Redwood framework that handles video data. We'll make a smart contract to handle our blockchain interactions. Then we'll set up the Redwood distributed app that will work with the blockchain.

Background on DApps

A DApp is very similar to a regular app. The only difference is that the back-end runs on a decentralized network instead of a central server that might host APIs or other services. It uses the Ethereum blockchain to store data and it has smart contracts to handle the business logic.

By using smart contracts, DApps don't have an owner. A smart contract is like a set of rules that every part of the network has to follow. Once the smart contract has been deployed to Ethereum, you can't change it. That means no companies or individuals can change the instructions for that set of rules in any way.

Ethereum

For a little context, Ethereum is a decentralized, open-source blockchain that has smart contract functionality. This is used as the network to host smart contracts. Anybody can join an Ethereum network and they will automatically follow the rules in the smart contract.

Setting up a Redwood app

Now that we have a little background on what we'll be making, let's start by making the Redwood app. To do this, open a terminal and run:

yarn create redwood-app user-dapp

This will generate new directories and files for the project that covers everything from the front-end to the back-end, including a database. Even when you're working with a DApp, there might be reasons you want to track data in a more common way, like easier data processing.

With the app created, you should see two main directories: api and web. The api folder holds all of the logic for the GraphQL back-end and the code to manage the database transactions. The web folder, which is where we'll be focused, holds all of the front-end logic and user interface.

Some Installations

You'll need to download Ganache to set up a local Ethereum network that you can develop on. Once you have it installed, you can use the "Quickstart" option.

You'll also need to install Truffle with the following command in the web directory.

yarn add truffle

This is how we'll deploy the smart contract to the local Ethereum network.

There are a few dependencies that need to be installed too. In the web directory run:

yarn add truffle truffle-contract web3

This gives us everything we need for the smart contract.

Initializing the Truffle project

Now run the following in the web directory:

yarn truffle init

This will create an initial migration and the smart contract for it in the web directory. Now we'll jump straight into some code since we have everything set up.

Writing the smart contract

Inside the web > contracts directory, add a new file called VideoList.sol. This is where we'll write some Solidity code to define the rules for this contract. It looks very similar to JavaScript, but it's not the same language. Copy and paste the following code into this new file.

pragma solidity ^0.5.0;

contract VideoList {
  uint public videoCount = 0;

  struct Video {
    uint id;
    string url;
  }

  mapping(uint => Video) public videos;

  constructor() public {
    createVideo("https://res.cloudinary.com/milecia/video/upload/c_pad,h_360,w_480,q_70,du_10/elephant_herd.mp4");
  }

  function createVideo(string memory _content) public {
    videoCount ++;
    videos[videoCount] = Video(videoCount, _content);
  }
}

Let's walk through what happened here. We start by defining the version of Solidity we want to work with. Then we create the definition for the contract. In this example, the contract is called VideoList.

In the contract, we have a publically exposed videoCount variable that holds how many videos have been added to the blockchain.

Next, there's a struct that defines a Video record. It has an integer id value and a string url value. Then we map all of the videos into a public videos array.

Using the constructor, we add a default video to the blockchain when the smart contract is deployed. Lastly, we have a function that will let us add new videos to the blockchain.

This is the whole smart contract! All that's left to do is create a migration for it and deploy it to the local blockchain.

Migrations and deploys

Before we actually do the migration and deploy, there's a little config file we need to add. In the web directory, add a new file called truffle-config.js. Inside the file, paste the following code.

module.exports = {
  networks: {
    development: {
      host: "127.0.0.1",
      port: 7545,
      network_id: "*" // so it can match any network id
    }
  },
  solc: {
    optimizer: {
      enabled: true,
      runs: 200
    }
  }
}

This is how we connect to the local Ethereum blockchain that's running through Ganache. These are the default values in Ganache and you can see them directly in the app.

Then we'll need to add a new migration file to the migrations folder. Create a new migration file called 2_deploy_contracts.js. We put the number at the beginning of the migration file so the network knows which order they should be run in.

Open this file and add the following code.

const VideoList = artifacts.require("./VideoList.sol");

module.exports = function(deployer) {
  deployer.deploy(VideoList);
};

This is how we deploy the VideoList smart contract we created.

With this in place, we can run the migration for the smart contract. In the web directory, run:

truffle migrate

You should see that the migration has run successfully. Now let's take a look at the smart contract in the Truffle console. We'll need the address of the smart contract for a later part of this article, so let's grab it while we're here.

In the web directory, run:

truffle console

This should bring you to an instance of the smart contract we deployed with the migration. Let's run so code in the console to get an instance of the contract with a function.

videoList = await VideoList.deployed()

We have to interact with the blockchain in an async manner, that's why we're using the await keyword in the Truffle console. Now let's get the address for this contract because we'll need it in the DApp.

videoList.address

This should return a string similiar to this:

0x82293fe0BE6cCbA6Eb9bd6d5824fC6ACeB6d3957

Since we have the smart contract built and deployed, we can turn our attention to the DApp which uses the data from the blockchain.

Working on the front-end

We'll take advantage of a Redwood command to get started on the front-end. We need a page that lets users interact with the DApp. Leave the web directory and go to the project root in the terminal and run the following command.

yarn rw g page dapp /

This will generate the page component, a Storybook component for the page, and a test for the page. It'll also add the route for this new page to the Routes.tsx file. Since we added the / in the generate command above, it makes this new page the root page for the app.

Back in the web directory, take a look inside src > pages > DappPage. This has all the files we talked about. Our focus will be on DappPage.tsx. Open this file and delete everything out of it.

Connecting to the Ethereum blockchain with Web3.js

The first thing we need to do is make a new file called config.tsx in the web > src directory. This is where we'll add some config values that let the front-end connect to the blockchain network we have running with Ganache.

Remember that address we got for our smart contract earlier? It's ok if you don't. All you have to do is open a terminal in the web directory and run the following commands to get that address again.

truffle console
videoList = await VideoList.deployed()
videoList.address

In the config.tsx file, add the following line with your own smart contract address.

export const VIDEO_LIST_ADDRESS = '0x82293fe0BE6cCbA6Eb9bd6d5824fC6ACeB6d3957'

Next, you'll have to get an array of values for the ABI of the smart contract. This describes the smart contract behavior and functionality to the front-end. You'll find this in web > build > contracts > VideoList.json. In the json file, you'll see a key-value pair named "abi". Copy that whole array and add the following code to config.tsx like this.

export const VIDEO_LIST_ABI: any = [
  {
    "constant": true,
    "inputs": [],
    "name": "videoCount",
    "outputs": [
      {
        "name": "",
        "type": "uint256"
      }
    ],
    "payable": false,
    "stateMutability": "view",
    "type": "function",
    "signature": "0xc61b5f4c"
  },
  {
    "constant": true,
    "inputs": [
      {
        "name": "",
        "type": "uint256"
      }
    ],
    "name": "videos",
    "outputs": [
      {
        "name": "id",
        "type": "uint256"
      },
      {
        "name": "url",
        "type": "string"
      }
    ],
    "payable": false,
    "stateMutability": "view",
    "type": "function",
    "signature": "0xe6821bf5"
  },
  {
    "inputs": [],
    "payable": false,
    "stateMutability": "nonpayable",
    "type": "constructor",
    "signature": "constructor"
  },
  {
    "constant": false,
    "inputs": [
      {
        "name": "_content",
        "type": "string"
      }
    ],
    "name": "createVideo",
    "outputs": [],
    "payable": false,
    "stateMutability": "nonpayable",
    "type": "function",
    "signature": "0x8e878969"
  }
]

With this config file in place, let's import a few things in DappPage.tsx.

import { useState, useEffect } from 'react'
import Web3 from 'web3'
import { VIDEO_LIST_ABI, VIDEO_LIST_ADDRESS } from '../../config'

Now let's build the DappPage component. We'll start with just the outline of the component and a few states.

export const DappPage = () => {
  const [account, setAccount] = useState<string>('')
  const [videoList, setVideoList] = useState<any>()
  const [videos, setVideos] = useState([])
}

Next, we'll call the function that will connect to the Ethereum network. We're using the useEffect hook here because we only want this to happen when the page initially loads. So right below the states we defined, add this code.

useEffect(() => {
  loadData()
}, [])

Let's jump into writing the loadData method. This is where we'll actually connect to the network and read data from the blockchain.

const loadData = async () => {
  const web3 = new Web3('http://localhost:7545')

  const accounts = await web3.eth?.getAccounts()

  setAccount(accounts[0])

  const videoList = new web3.eth.Contract(VIDEO_LIST_ABI, VIDEO_LIST_ADDRESS)
  setVideoList(videoList)

  const videoCount = await videoList.methods.videoCount().call()

  for (var i = 1; i <= videoCount; i++) {
    const video = await videoList.methods.videos(i).call()
    setVideos([...videos, video])
  }
}

This is an async function because we want to wait for the blockchain to handle the request. We make a new instance of Web3 that connects to the local Ethereum blockchain we have running. Then we get the accounts associated with this blockchain and grab the first one. We'll need this a little later.

Next, we pass in the config values we wrote earlier to interact with the smart contract. We're getting the videoList contract and fetching the videoCount to see how many videos are available.

Then we loop through all of the videos in the blockchain and save them to the app's state.

Now we can return a view to the page that displays the smart contract id and the videos we've fetched from the blockchain. Right below the loadData method, add the following return statement.

return (
  <div>
    Dapp account id: {account}
    <ul id="videoList">
      {videos.map((video, key) => {
        return (
          <div key={key}>
            <label>
              <video src={video.url}></video>
            </label>
          </div>
        )
      })}
    </ul>
  </div>
)

If you go to the root of the project in a terminal and run yarn rw dev, you should see something similar to this in the browser.

You've officially connected an app to an Ethereum blockchain using a smart contract you wrote! All that's left is adding a way for users to add new videos to the blockchain.

Adding the videos to the blockchain

For the last bit of functionality, we'll use the Cloudinary upload widget to add videos directly to the blockchain.

We need to add the react-cloudinary-upload-widget package in a terminal in the web directory.

yarn add react-cloudinary-upload-widget

Then we'll add another import line to DappPage.tsx below the others.

import { WidgetLoader, Widget } from 'react-cloudinary-upload-widget'

Now we can write the function to add a video to the blockchain. After the loadData function, add this code.

const createVideo = (content) => {
  videoList.methods.createVideo(content).send({ from: account, gas: 4712388 })
    .once('receipt', (receipt) => {
      console.log(receipt)
    })
}

This is how we use the createVideo method we defined in the smart contract. One thing to note is that we need to send a certain amount of gas with this request. The amount of gas you have is tied to the account you're connected with. Each transaction in a smart contract has a gas price, but since we didn't change any default values 4712388 is what the contract expects as a gas payment.

Now we'll define the callback that will give us a response from Cloudinary when the video has successfully uploaded. Right below the createVideo function we just wrote, add this.

const successCallBack = (results) => {
  const videoInfo = results.info
  const url = videoInfo.url

  createVideo(url)
}

This will be called in the Widget when we get a success response from Cloudinary. It'll take the URL from Cloudinary and add it to the blockchain. That means it's finally time to add that widget to the return statement. Below the line that displays the account id, add the following code.

<WidgetLoader />
<Widget
  sources={['local', 'camera']}
  cloudName={'test_name'}
  uploadPreset={'fwe9ewffw'}
  buttonText={'Open'}
  style={{
    color: 'white',
    border: 'none',
    width: '120px',
    backgroundColor: 'green',
    borderRadius: '4px',
    height: '25px',
  }}
  folder={'test0'}
  onSuccess={successCallBack}
/>

This is how we connect to Cloudinary and get URLs for videos we upload. You'll need to log in to your Cloudinary account and get the cloudName and uploadPreset name from the dashboard. Now you should see a new "Open" button in the browser.

If you click that button, you'll see the upload widget.

Go ahead and upload a new video and then reload the page. You should see your new video similar to this.

You have a fully functioning DApp now! Feel free to add more functionality to the smart contract!

Finished code

You can check out some of the code in this Code Sandbox or clone the project from the user-dapp folder of this repo.

Conclusion

DApps are a cool way to interact with blockchains. Some good next steps would be learning more about Solidity and smart contracts or just making more DApps with other frameworks!

Building a Virtual Beat Box in Redwood

Milecia — Thu, 28 Oct 2021 13:45:11 +0000

Sometimes you don't need to make a serious app to practice your JavaScript skills. We're going to play with a full-stack music app! It'll be a virtual beat box that you can make music with and store it in a database.

Setting up the app

We'll just jump in and start building the Redwood app because it has integrations to make it easier to set up the front-end and back-end. So in a terminal, run this command:

yarn create redwood-app virtual-music-box

This generates a new Redwood project with a lot of new files and directories for us and we'll be focused on the web and api directories. The web directory will hold all of the front-end code, which we'll get to a little later. The api directory contains all of the back-end code.

To get started, let's write the back-end code.

Building the back-end

Redwood uses GraphQL to handle the back-end and Prisma to work with the database. We'll start by setting up a local Postgres instance. If you don't have Postgres installed, you can download it here.

Now you're going to add a new file to the root of the project called .env. Inside that file, you'll need to add the connection string for your Postgres instance. It should look similar to this:

DATABASE_URL=postgres://postgres:admin@localhost:5432/mixes

With this connection string in place, let's move to the schema.prisma file in the api > db directory. This is where you can add the models for your database. In this file, you'll see a provider with sqlite as the value. We're going to update that to postgresql like this:

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

This is where we connect to the database using the connection string in that .env file we made. Next, we'll add a model to hold the music we make.

Making the model

You can delete the example model in prisma.schema and replace it with this:

model Mix {
  id     String @id @default(cuid())
  name   String
  sample String
}

We're creating a new table called Mix that has a cuid for the id, a name for the song, and the sample of notes that make up the song. Since we have the model we need in place, we can run a database migration now with this command:

yarn rw prisma migrate dev

This will create a new database on your local Postgres server and it will create a new migrations directory inside api > db with the SQL to update the database.

Creating the GraphQL types and resolvers

With the database ready to go, we can start working on the GraphQL server. A cool feature that Redwood has is autogenerating the types and resolvers for the basic CRUD functionality we need to get going. We'll take advantage of this with the following command:

yarn rw g sdl mix --crud

This creates the GraphQL types and resolvers we need to create, update, delete, and read mixes we want to work with. If you take a look in api > src > graphql, you'll see a new file called mixes.sdl.ts. This has all of the types we need based on the model we created earlier.

Next, take a look in api > src > services > mixes. This holds the file for our resolvers and testing. If you open mixes.ts, you'll see all of the resolvers for create, read, update, and delete functionality already written for us.

So now we have a fully functional back-end! That means we can switch our focus to the front-end where we actually get to make music.

Moving to the front-end

We have to set up an interface for our users to select notes to play. We'll use a grid to handle this. There are a few libraries we need to install before we start working on the component.

In a terminal, go to the web directory and run these commands:

yarn add tone
yarn add styled-components

The tone library is how we'll add sound to the browser. We'll use styled-components to help make the grid.

Let's start by creating a new page in Redwood. In a terminal, go back to the root directory of the project and run this:

yarn rw g page mixer /

This will create a new page for the main view of our app. It automatically updates Routes.tsx for us and if you take a look in web > src > pages > MixerPage, you'll see the component, a Storybook story, and a unit test. Redwood generates all of this for us from that command above.

Adding the mixer

Go ahead and open MixerPage.tsx and delete everything out of it. We'll be making a completely new component. To start, we'll add all of the imports we need.

import { useState } from 'react'
import { useMutation } from '@redwoodjs/web'
import * as Tone from 'tone'
import styled from 'styled-components'

Now we can define the MixerPage component and a few styled components to get started. We'll write the code and then walk through it.

const Flex = styled.div`
  display: flex;
  flex-direction: row;
  flex-wrap: wrap;
`

const Square = styled.div`
  background-color: #ABABAB;
  border: 2px solid #313131;
  height: 250px;
  width: 250px;
`

const MixerPage = () => {
  const notes = ['G3', 'A6', 'C9', 'B5', 'D7', 'F1', 'E8', 'A7', 'G6', 'B1', 'F4', 'C5']

  return (
    <>
      <h1>Mixer Page</h1>
      <Flex>
        {notes.map(note => (
          <Square key={note} onClick={() => console.log(note)} />
        ))}
      </Flex>
      <button onClick={() => console.log(mix)}>Save Sounds</button>
    </>
  )
}

export default MixerPage

First, we make a couple of styled components. The Flex component is a flexbox we're able to make the grid shape we need for the beat box. The Square component is a colored box that represents a square in our grid.

Then we define the MixerPage component and add the export statement at the bottom of the file. Inside the component, we add a notes array that holds the notes we want users to be able to play.

Next, we add the return statement where we create our grid based on the number of notes in the array. We map over the notes array and add an onClick callback to work with notes. Then there's a save button that will eventually connect to the back-end and store all of the beats we make.

If you run the app with yarn rw dev, you should see something like this in your browser.

Connecting the back-end to save beats

There's one more thing we need to add and that's the connection to the back-end. We'll add our GraphQL mutation for saving new beats right below the Square styled component.

const CREATE_MIX_MUTATION = gql`
  mutation CreateMixMutation($input: CreateMixInput!) {
    createMix(input: $input) {
      id
    }
  }
`

Now we can start adding the real functionality to our grid. Inside the MixerPage component, add this code above the notes array:

const [createMix] = useMutation(CREATE_MIX_MUTATION)
const [mix, setMix] = useState([])

This gives us access to the createMix mutation defined in the GraphQL resolvers we made earlier. It also creates the mix state we'll use to store the notes on in the database.

Now we get to do the fun thing and add the sound to our app. Below the mix state, add this line:

const mixer = new Tone.MembraneSynth().toDestination()

This is how we use the tone library to play some kind of sound through our speakers. You can check out some of the others in their docs.

Playing the notes

With the mixer object ready, we need to add the function that will play the notes when a user clicks on a Square.

const playNote = (note) => {
  mixer.triggerAttackRelease(note, "6n")

  const isSet = mix.includes(note)

  if (!isSet) {
    setMix([...mix, note])
  } else {
    const updateMix = mix.filter((mixNote) => mixNote !== note)
    setMix(updateMix)
  }
}

This playNote function takes in a string for the note value, which will be the note for the clicked Square. Then we use the mixer to actually play the sound with the triggerAttackRelease method and we pass it the note and a string for how we want the note to sound. You can play with this value and see how it changes the sound.

Next, we do a quick check to see if the note is already in the mix state. If it is not in the mix state, we'll update the state. Otherwise, we will filter out the note from the existing state and update the mix state.

The other function we need to make will handle saving the mixes we make.

const saveMix = (mix) => {
  const input = { name: `mix-${mix[0]}`, sample: mix.join() }
  createMix({ variables: { input } })
}

This function takes the mix state and creates the input value we need to pass to the GraphQL mutation. Then we call the createMix mutation with the input value and save the mix to the database.

Now we're ready to wrap things up by calling these functions in our elements.

Updating the elements

We need to update some props on the Square element.

<Square key={note} selected={mix.includes(note)} onClick={() => playNote(note)} />

We're using the selected prop to update the color of a square. That means we'll have to make a minor update to the Square styled component to take advantage of this prop.

const Square = styled.div`
  background-color: ${props => props.selected ? '#ABABAB' : '#EFEFEF'};
  border: 2px solid #313131;
  height: 250px;
  width: 250px;
`

Now when a note is selected or unselected, the color of the square will update.

Next, we need to call the saveMix function when the button is clicked.

<button onClick={() => saveMix(mix)}>Save Sounds</button>

This takes the current mix state and passes it to the GraphQL mutation. If you run the app and click a few squares, you should see something like this.

There's one more thing we can add to take this app to the next level. We can play specific videos after the mix has been saved.

Adding media

We'll start by adding an array with links to different videos hosted in Cloudinary. Using Cloudinary just makes it easier to work with media files instead of worrying about hosting them ourselves in AWS or storing things in the database.

So right under the notes array, add the following videos array:

const videos = ['https://res.cloudinary.com/milecia/video/upload/v1606580790/elephant_herd.mp4', 'https://res.cloudinary.com/milecia/video/upload/v1606580788/sea-turtle.mp4', 'https://res.cloudinary.com/milecia/video/upload/v1625835105/test0/tq0ejpc2uz5jakz54dsj.mp4', 'https://res.cloudinary.com/milecia/video/upload/v1625799334/test0/ebxcgjdw8fvgnj4zdson.mp4']

Feel free to make your own Cloudinary account and use some videos you like!

This has a few video links that we'll use to display something when a mix has been saved. Now we need to create a new state to store the video source URL for when we get ready to render. You can add this below the mix state:

const [video, setVideo] = useState('')

We also need to add a video element below the button and its source is the video state. The video element will only display when the video state is not an empty string.

{video !== '' &&
  <video src={video} width='480' height='360' controls>
  </video>
}

The last bit of code we need is to update the video state when we've successfully saved a beat. We'll add this to the saveMix method after we call the mutation.

const randomInt = Math.floor(Math.random() * (videos.length - 1))
setVideo(videos[randomInt])

This gets a random video from the array and makes it the video that plays after a successful submission. After you save a mix, you should see something like this in the browser.

Finished code

You can take a look at the front-end code in this Code Sandbox or you can check out the whole project in the virtual-music-box folder of this repo.

Conclusion

There are a lot of different ways you can play with Tone.js to improve your apps. You could use it to make things more accessible for users. You can add a different level of entertainment for users that work with your app frequently. Or you can start teaching music theory online.

Web apps with sound give users a different experience and it's also fun to work with. Don't be afraid to try new things! You never know what you might find useful or interesting.

Making an Audio Visualizer with Redwood

Milecia — Tue, 19 Oct 2021 01:20:45 +0000

Working with audio on the web is an overlooked way of communicating information to users. You can take audio files and give users a real-time visualization of what's playing.

In this tutorial, we're going to make an audio visualizer with P5.js in the Redwood framework. It will take sounds that it picks up from the mic and visualize them. We'll also add a way to save a snapshot of the visual when we push a button.

Creating the app

To get started, we'll make a new Redwood app. Open a terminal and run the following command.

yarn create redwood-app audio-visualizer

This will generate a lot of files and directories for you. The main two directories you'll work in are the api and web directories. The api directory is where you will handle all of your back-end needs. This is where you'll define the models for your database and the types and resolvers for your GraphQL server.

The web directory holds all of the code for the React app. This is where we'll be focused since everything we're doing is on the front-end. We'll start by importing a few JavaScript libraries.

Setting up the front-end

Before we get started, I just want to note that if you're following along with TypeScript, you might run into some issues with the P5 sound library. I ran into issues where it kind of worked, but it also kind of didn't.

That's why we're going to be working with JavaScript files even though I usually work with TypeScript. P5 is a little tricky to get working in React and it took me a few different tries to figure out how to get this working.

We're going to import the P5 libraries now, but we won't do it using npm or yarn. We're going to go straight to the index.html and add a couple of script tags with links to the P5 files we need. So in the <head> element, add the following code after the <link> tag.

<script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/1.4.0/p5.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/1.4.0/addons/p5.sound.min.js"></script>

Now that we have the libraries in the project, we need to set up a page to render our visualizer. We'll take advantage of some Redwood functionality for this. In the terminal, run this command.

yarn rw g page visualizer /

This command will create a new page under web > src > pages called VisualizerPage.js. You'll also see a Storybook file and a test file. These were generated with that Redwood command. This is a good time to run the app and see what it looks like.

In the terminal, run the following command to start the app.

yarn rw dev

This will start the front-end and back-end of the Redwood app and when your browser loads, you should see something similar to this.

We'll make a quick update to the text on the page. So inside the VisualizerPage.js file in web > src > page > VisualizerPage, update the code to the following.

import { MetaTags } from '@redwoodjs/web'

const VisualizerPage = () => {
  return (
    <>
      <MetaTags
        title="Visualizer"
        description="Visualizer description"
      />

      <h1>Simple audio visualizer</h1>
      <p>
       This will take any sounds picked up by your mic and make a simple visualization for them.
      </p>
    </>
  )
}

export default VisualizerPage

Now we're ready to start adding the code we need to pick up sound from a user's mic and render a visualization.

Adding the music player

First, we'll add a new import statement. We're going to need to reference an element, so we're going to take advantage of the useRef hook. At the end of your import statements, add this one.

import { useRef } from 'react'

Then inside of the VisualizerPage component, add this line to make a reference we can use on an element.

const app = useRef();

Now inside of the return statement, add this element right before the closing tag.

<div ref={app}></div>

With these things in place, we're ready to use that <div> as our visualizer element.

Integrating the visualizations

We can start using P5 to create the visualization. We'll add one more imported hook to the file. We'll be adding the useEffect hook. So in your existing import statements, add useEffect to the existing useRef line so it's all in one import statement.

import { useRef, useEffect } from 'react'

Then inside the VisualizerPage component, add the following hook beneath the useRef variable.

useEffect(() => {
  let newP5 = new p5(sketch, app.current);

  return () => {
    newP5.remove();
  };
}, []);

This useEffect hook initializes our instance of a P5 canvas in the app ref we created. If anything weird happens, it'll remove the P5 instance. This setup only happens when the page is initially loaded. That's why we have the empty array as a parameter.

Next, we can define what sketch is. This is how we tell P5 what it should render, how it should do it, and when it should update. We'll build this piece by piece.

Let's define the sketch function.

const sketch = p => {
  let mic, fft, canvas;

  p.setup = () => {
    canvas = p.createCanvas(710, 400);
    p.noFill();

    mic = new p5.AudioIn();
    mic.start();
    p.getAudioContext().resume()
    fft = new p5.FFT();
    fft.setInput(mic);
  }
}

We start by taking the current instance of P5 as a variable called p. Then we define a few variables to hold a value for our mic, to handle some fft operations, and to create the canvas element.

Then we define what P5 should do on setup. It creates a new canvas with the width and height we defined. We decide it shouldn't have any kind of fill in the canvas.

Now things start to get interesting. We'll grab our mic input object with the AudioIn method. Then we'll call mic.start to get the mic to start listening for sound. Because most browsers don't let you automatically start recording a user's mic, we have to add the line to resume listening.

Next, we create an fft object that we use to handle the input from the mic. This is important for our visualizer to account for different pitches it picks up through the mic.

Since we have the setup ready to go, we need to define what should be drawn in the canvas. Below the setup method we just defined, add this code.

p.draw = () => {
  p.background(200);

  let spectrum = fft.analyze();

  p.beginShape();
  p.stroke('#1d43ad')
  p.strokeWeight('3')

  spectrum.forEach((spec, i) => {
    p.vertex(i, p.map(spec, 0, 255, p.height, 0));
  })

  p.endShape();
}

First, this changes the background color to a shade of grey. Then we use fft.analyze to get the amplitude or height of each frequency that's picked up from the mic.

Then we use beginShape to tell P5 we're going to be drawing some type of line. Next we give the line a stroke color and a strokeWeight to add some definition to how the line will look.

Next we take each point in the spectrum from our fft and add a vertex for the points on the line. This will give us a visual representation of how the sound's pitches break down. Once all of those vertices are added to the shape, we finish the line by calling endShape.

All that's left now is saving a snapshot of the image when a key is pressed. We'll do that with the following code. Make sure to add this below the draw method we just finished.

p.keyPressed = () => {
  if (p.keyCode === 39) {
    p.saveCanvas('canvasSnapshot', 'png')
  }
}

This is one of the ways you can interact with P5. Take a look through their docs if you want to learn more. I chose the right arrow, but you can feel free to change this to any other key. Just make sure you update the keyCode value.

Right now, if a user presses the right arrow key, a snapshot of the visualization will be downloaded to their device. It'll be a png file named canvasSnapshot.

That's it! All that's left is to refresh the browser and make sure your mic permissions are adjusted. You should see something like this in your browser now.

If you hit the right arrow key, you'll get an image that looks similar to this.

Finished code

If you want to take a look at this working, you can check out this Code Sandbox or you can get the code from the audio-visualizer folder in this repo.

Conclusion

Working with audio on the web can be an interesting way to provide data to users. It can help make your apps more accessible if you use it correctly. You can also generate images that might give you a better understanding of the sound you're working with. This definitely comes up a lot in machine learning!

Making a Meal Picker with Redwood

Milecia — Thu, 07 Oct 2021 20:37:25 +0000

Deciding what to eat every day is something that a lot of us struggle with. It'd be so much easier if there was a button you could push and it would choose one of your favorite meals for you.

That's why we're going to make a meal picker in this tutorial. We'll use Redwood to create the front-end and back-end of the app which will let us save recipes and choose a random meal. We'll also be using Cloudinary to host the video we have associated with the recipes.

Setting up the app

To get started, let's make a new Redwood app that uses TypeScript. In a terminal, run this command.

yarn create redwood-app --typescript meal-picker

This will generate a lot of new files and folders in the meal-picker directory. The main two directories are web and api. The web folder contains all of the code for the front-end and the api directory contains all of the code for the back-end.

Most times, it's a good practice to start building the data model of a new app first.

Building the back-end

We'll start by opening the prisma.schema file in api > db directory. This file holds all of the models for the tables we'll have in the database. We'll be using a local Postgres instance, so if you need to download that you can find the right version here.

The first thing we'll do is update the provider value to postgresql. Next, we need to create a .env file in the root of the project. You'll see the DATABASE_URL being read from the environment below the type of database we're using. In the .env file, add the connection string to your local Postgres instance. It might look similar to this.

DATABASE_URL=postgres://postgres:admin@localhost:5432/meal_picker

Creating the model

Now you have everything set to connect to your database. We need to define the model for the meals we'll be saving to choose from. You can delete the UserExample model and replace it with this.

model Meal {
  id      String @id @default(cuid())
  title   String
  recipe  String
  video   String
}

This model defines a table that will hold all of the details for our meals. There has to be a way for users to input their favorite meals and all of the details. With the model ready, we can go ahead and run the migration to get these changes on the database.

yarn rw prisma migrate dev

That will define the Meal table in Postgres. So now we can use one of the Redwood commands to generate this CRUD functionality for us.

Creating the meal collection management functionality

We'll need to have both the GraphQL back-end in place and the front-end in place to allow users to add, edit, and delete meals. This normally takes a bit of time, but the following command generates all of that for us.

yarn rw g scaffold meal

Check the api > src > graphql directory and you should see meals.sdl.ts file that has all of the types for the queries and mutations we need. If you check in api > src > services > meals, you'll see three files. Two of them are for tests and the meals.ts file holds all of the resolvers for our queries and mutations. These already connect to the database so we have our entire back-end created!

Moving to the front-end

Now that we have the GraphQL server ready to go, let's take a look at the files the scaffold command created on the front-end. In web > src > pages > Meals, you'll see several new directories that correspond to different views of the CRUD for meals.

If you take a look in web > src > components > Meal, you'll see a number of components that we created. These components interact with and display the data that we get from the back-end. It's worth taking the time to peek at these different files and see how they work, but you can still run the app and see all of the CRUD in action without ever looking at the code.

In your terminal, run this command and navigate to http://localhost:8910/meals.

yarn rw dev

You should see something like this in your browser.

Now add a few entries by clicking the "New Meal" button. This will bring up a new page and let you add the details.

If you haven't uploaded any videos for your meals, take a second to go to your Cloudinary account and add those. Make sure you grab the URLs for the videos you want to use because you'll add them to your new meal entries.

Once you've added a few meals, you should see a table that lists all of your entries.

That's everything we need to handle the CRUD functionality for our meals. You might think of this as an admin area in the app. Redwood generated all of this for us with just one command. All that's left is making the random meal picker page.

Making the picker page

Let's make a new page for the picker. We'll use another Redwood command.

yarn rw g page picker /

This updates our routes to make the picker page the root page and it generates some files for us. Go to web > src > pages > PickerPage and open PickerPage.tsx. This is where we'll make the button that will tell us what to eat.

We'll get rid of a lot of the boilerplate code in the PickerPage component. Let's start by adding the import statements for the methods we'll be using. So your list of import statements should look like this.

import { useQuery } from '@redwoodjs/web'
import { MetaTags } from '@redwoodjs/web'
import { useState } from 'react'

Now let's add the GraphQL query we need to get all of the meals we have available to choose from. This goes right below the import statements.

const GET_MEALS = gql`
  query {
    meals {
      title
      recipe
      video
    }
  }
`

One more quick thing before we start using this query. Since this is a TypeScript app, let's add the type for a single meal. Below the query just wrote, add the Meal type.

interface Meal {
  title: string
  recipe: string
  video: string
}

When we get ready to work with the meals data, now we know exactly what to expect. Now we get to delete a lot of code. Inside the PickerPage component, delete everything except the <MetaTags> element. Your PickerPage.tsx should look like this now.

import { useQuery } from '@redwoodjs/web'
import { MetaTags } from '@redwoodjs/web'
import { useState } from 'react'

const GET_MEALS = gql`
  query {
    meals {
      title
      recipe
      video
    }
  }
`

interface Meal {
  title: string
  recipe: string
  video: string
}

const PickerPage = () => {
  return (
    <>
      <MetaTags
        title="Picker"
      />
    </>
  )
}

export default PickerPage

All that's left is adding the data and the elements to display it.

Handling the data

Let's add a new meal state in the component. We'll use our Meal type to define what values are expected.

const [meal, setMeal] = useState<Meal>()

Next we'll use the useQuery hook to fetch our data from the GraphQL server.

const { loading, data } = useQuery(GET_MEALS)

We get both the data and a loading state for it. That way we can account for any latency in the request and show the users a loading screen. If we don't handle this, the app will likely crash because the data isn't available yet. Right below the useQuery call, we'll add the code to handle this loading state.

if (loading) {
  return <div>Loading...</div>
}

The last function we need to add before creating the elements to show our random meal will actually be responsible for choosing that meal. When we click a button on the screen, it'll call this function and set the meal state to some random selection.

const loadMeal = () => {
  if (data.meals.length !== 0) {
    const max = data.meals.length
    const index = getRandomInt(0, max)
    setMeal(data.meals[index])
  }
}

There is a tiny helper function we for to get that random integer. Add this code below the PickerPage component.

function getRandomInt(min, max) {
  min = Math.ceil(min);
  max = Math.floor(max);
  return Math.floor(Math.random() * (max - min) + min);
}

We have the data in place and all of the accompanying functions we need. Let's finally add the elements to display everything.

The button and meal display

Below the <MetaTags> element, add these elements.

<h1>{meal ? meal.title : 'Find out what you are going to eat'}</h1>
<button onClick={loadMeal} style={{ fontSize: '18px', padding: '24px 32px', width: '500px' }}>Tell me what to eat</button>

The text on the page will change based on whether or not you've had a random meal selected. Then there's the button with a few styles on it that will call the function to choose a new random meal.

If you run the app again with yarn rw dev, you'll see something like this in your browser.

The last piece of code is to display the info for the randomly selected meal. We'll do this with a conditional render statement below the <button>.

{meal &&
  <>
    <p>{meal.recipe}</p>
    <video src={meal.video} controls height='350' width='500'></video>
  </>
}

This will display the recipe and the video whenever the button is clicked and a meal is selected. Now if you look in the browser, you should see something like this.

That's it! You now have a meal picker that will make it hard for you to say you can't decide what to eat anymore.

Finished code

If you want to check out the finished front-end and back-end code, check out the code in the food-picker folder of this repo. You can see an example of the front-end in this Code Sandbox.

Conclusion

Not every project you work on has to be super detailed. Sometimes you just need something to prove a concept or you want to make something for yourself. I know I've definitely used this app to pick what I'm going to eat more than I want to admit.

Adding Data to Build a More Generic Model

Milecia — Wed, 06 Oct 2021 18:46:33 +0000

You might be in the middle of training a model and then the business problem shifts. Now you have this model that has been going through the training process with a specific dataset and you need to make the model more generic.

There's likely something that your model learned that can be useful on this new dataset, so you might not have to restart the entire training process. We'll do an example of updating a pre-trained model to use a broader dataset with DVC. By the end of this, you should see how you can handle this quickly and start running new experiments to get a more generic model.

The original pre-trained model

For this post, we'll be making a more generic image classifier by taking the original dataset with bees and ants and adding cats and dogs to it. You can clone this GitHub repo to get the current bees and ants model and check out this post on how we experimented with both AlexNet and SqueezeNet to build this model.

So we're starting from our current bees and ants model and extending it to classify dogs and cats as well. We'll start by adding some cats and dogs data to our validation data and do some experiments with the current model to see how it performs on generic data.

Then we'll add the cats and dogs data to the training data and watch how the model improves as we run experiments.

Updating the dataset with DVC

To add the new cats and dogs dataset to the project, we'll use this DVC command.

$ dvc get https://github.com/iterative/dataset-registry blog/cats-dogs

This downloads a sample dataset with images of cats and dogs. You can use this command to download files or directories that are tracked by DVC or Git. This command can be used from anywhere in the file system, as long as DVC is installed.

This will make a new directory called ./cats-dogs/data/ that was downloaded from the DVC remote and it has images for cats and dogs. Now we can slowly add in the new data to the existing data.

We'll start by moving the val data for cats and dogs from the /cats-dogs/data/ directory to the corresponding directory in
data/hymenoptera_data.

Just a quick note, cats and dogs don't really belong in the hymenoptera directory since that's specific to ants and bees, but it's the easiest and fastest way to add the data for this tutorial.

With this new data in place, we can start training our model.

Running new experiments with generic data

With the updated data, let's run an experiment on the model and see how good the results are. To run a new experiment, open your terminal and make sure you have a virtual environment enabled. Then run this command:

$ dvc exp run

Once the training epochs are finished, run the following command.

$ dvc exp show --no-timestamp \
--include-metrics step,acc,val_acc,loss,val_loss \
--include-params lr,momentum

The --no-timestamp hides the timestamps from table. The --includes-metrics option lets us choose which metrics we want to show in the table. The --includes-params option does the same for hyperparameters. This gives us a table that's easier to read quickly.

┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━┓
┃ Experiment              ┃ step ┃     acc ┃ val_acc ┃    loss ┃ val_loss ┃ lr    ┃ momentum ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━╇━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━┩
│ workspace               │    3 │ 0.86885 │    0.46 │ 0.31573 │   3.7067 │ 0.001 │ 0.09     │
│ data-change             │    - │       - │       - │       - │        - │ 0.001 │ 0.09     │
│ │ ╓ 3b3a2a2 [exp-23593] │    3 │ 0.86885 │    0.46 │ 0.31573 │   3.7067 │ 0.001 │ 0.09     │
│ │ ╟ 93d015d             │    2 │ 0.83197 │ 0.41333 │ 0.36851 │   3.4259 │ 0.001 │ 0.09     │
│ │ ╟ d474c42             │    1 │ 0.79918 │ 0.43333 │ 0.46612 │    3.286 │ 0.001 │ 0.09     │
│ ├─╨ 1582b4b             │    0 │ 0.52869 │    0.39 │ 0.94102 │   2.5967 │ 0.001 │ 0.09     │
└─────────────────────────┴──────┴─────────┴─────────┴─────────┴──────────┴───────┴──────────┘

You'll notice that the validation accuracy is really low. That's because the training metrics are based on bees and ants while the validation metrics are based on bees, ants, cats, and dogs. If we looked at the validation metrics by class, they'd likely be better for bees and ants than cats and dogs.

That means we should probably add more data to the training dataset.

Adding the cats data to the training dataset

Let's add the train data for cats to the corresponding directory in data/hymenoptera_data and go through another experiment run with a different learning rate. With this new data, we can run another experiment. One important thing to note here is that we're using checkpoints in our experiments. That's how we get the metrics for each training epoch.

If we want to run a fresh experiment that doesn't resume training from the last epoch, we need to reset our experiment. That's what we're going to do with this command.

$ dvc exp run --reset

This will reset all of the existing checkpoints and execute the training script. Once it's finished, let's take a look at the metrics table with this command. It's the same as the one we ran last time.

$ dvc exp show --no-timestamp \
    --include-metrics step,acc,val_acc,loss,val_loss \
    --include-params lr,momentum

Now you'll have a table that shows both experiments and you can see how much better the new one did with the cats data added.

┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━┓
┃ Experiment              ┃ step ┃     acc ┃ val_acc ┃    loss ┃ val_loss ┃ lr    ┃ momentum ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━╇━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━┩
│ workspace               │    3 │ 0.91389 │    0.87 │ 0.20506 │  0.66306 │ 0.001 │ 0.09     │
│ data-change             │    - │       - │       - │       - │        - │ 0.001 │ 0.09     │
│ │ ╓ 9405575 [exp-54e8a] │    3 │ 0.91389 │    0.87 │ 0.20506 │  0.66306 │ 0.001 │ 0.09     │
│ │ ╟ 856d80f             │    2 │ 0.90215 │ 0.87333 │ 0.27204 │  0.61631 │ 0.001 │ 0.09     │
│ │ ╟ 23dc98f             │    1 │ 0.87671 │    0.86 │ 0.35964 │  0.61713 │ 0.001 │ 0.09     │
│ ├─╨ 99a3c34             │    0 │ 0.71429 │    0.82 │ 0.67674 │  0.62798 │ 0.001 │ 0.09     │
│ │ ╓ 3b3a2a2 [exp-23593] │    3 │ 0.86885 │    0.46 │ 0.31573 │   3.7067 │ 0.001 │ 0.09     │
│ │ ╟ 93d015d             │    2 │ 0.83197 │ 0.41333 │ 0.36851 │   3.4259 │ 0.001 │ 0.09     │
│ │ ╟ d474c42             │    1 │ 0.79918 │ 0.43333 │ 0.46612 │    3.286 │ 0.001 │ 0.09     │
│ ├─╨ 1582b4b             │    0 │ 0.52869 │    0.39 │ 0.94102 │   2.5967 │ 0.001 │ 0.09     │
└─────────────────────────┴──────┴─────────┴─────────┴─────────┴──────────┴───────┴──────────┘

There's another way you can look at the difference between the model before we added the cats data and after. If you run this in your terminal, you'll get a plot comparing the two experiments.

$ dvc plots diff exp-23593 exp-54e8a

The exp-23593 and exp-54e8a values are the ids for the experiments you want to compare. You'll see a new file gets generated in the dvc_plots directory in your project. That's where you'll find the index.html file you should open in your browser. You'll see something similar to this.

There's a huge difference in the accuracy of our model after we've added this additional data. Let's see if we can make it even better by adding the dogs data.

Adding the dogs data to the training dataset

We'll add the train data for dogs to the corresponding directory in data/hymenoptera_data just like we did for the cats data. Now we can run a new experiment with all of the new data included. We'll still need to reset the experiment like before, so run the following command.

$ dvc exp run --reset

Once the training epochs are finished, we can take one more look at that metrics table.

$ dvc exp show --no-timestamp \
--include-metrics step,acc,val_acc,loss,val_loss \
--include-params lr,momentum

Now we'll have all three experiments to compare.

┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━┓
┃ Experiment              ┃ step ┃     acc ┃ val_acc ┃    loss ┃ val_loss ┃ lr    ┃ momentum ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━╇━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━┩
│ workspace               │    3 │  0.8795 │ 0.90667 │ 0.29302 │  0.25752 │ 0.001 │ 0.09     │
│ **data-change**             │    - │       - │       - │       - │        - │ 0.001 │ 0.09     │
│ │ ╓ c20220f [exp-82f70] │    3 │  0.8795 │ 0.90667 │ 0.29302 │  0.25752 │ 0.001 │ 0.09     │
│ │ ╟ fcb5a0b             │    2 │ 0.85915 │ 0.92333 │ 0.38274 │  0.25257 │ 0.001 │ 0.09     │
│ │ ╟ 3768821             │    1 │ 0.80751 │ 0.84667 │ 0.47681 │  0.40228 │ 0.001 │ 0.09     │
│ ├─╨ 7e1b8fb             │    0 │ 0.64632 │    0.84 │ 0.87301 │  0.46744 │ 0.001 │ 0.09     │
│ │ ╓ 9405575 [exp-54e8a] │    3 │ 0.91389 │    0.87 │ 0.20506 │  0.66306 │ 0.001 │ 0.09     │
│ │ ╟ 856d80f             │    2 │ 0.90215 │ 0.87333 │ 0.27204 │  0.61631 │ 0.001 │ 0.09     │
│ │ ╟ 23dc98f             │    1 │ 0.87671 │    0.86 │ 0.35964 │  0.61713 │ 0.001 │ 0.09     │
│ ├─╨ 99a3c34             │    0 │ 0.71429 │    0.82 │ 0.67674 │  0.62798 │ 0.001 │ 0.09     │
│ │ ╓ 3b3a2a2 [exp-23593] │    3 │ 0.86885 │    0.46 │ 0.31573 │   3.7067 │ 0.001 │ 0.09     │
│ │ ╟ 93d015d             │    2 │ 0.83197 │ 0.41333 │ 0.36851 │   3.4259 │ 0.001 │ 0.09     │
│ │ ╟ d474c42             │    1 │ 0.79918 │ 0.43333 │ 0.46612 │    3.286 │ 0.001 │ 0.09     │
│ ├─╨ 1582b4b             │    0 │ 0.52869 │    0.39 │ 0.94102 │   2.5967 │ 0.001 │ 0.09     │
└─────────────────────────┴──────┴─────────┴─────────┴─────────┴──────────┴───────┴──────────┘

These results make sense for the experiments we've run. We're paying attention to the validation accuracy here because this gives us a fair comparison of what's happening as we add more data.

The first experiment's training metrics are for bees and ants. The second experiment's training metrics are for bees, ants, and cats. And the third experiment's training metrics are for all four classes. So we can't really compare these metrics.

We can look at a comparison between the experiments with the cats data and both the cats and dogs data.

$ dvc plots diff exp-23593 exp-54e8a exp-82f70

The results you see line up with what is expected for the validation metrics based on how we added the data to the training set. Now you can keep running experiments until you get your model tuned like you need it!

Conclusion

When you want to change datasets quickly and start tracking how they affect our model, using a DVC remote makes it easy to do so on different computers. You'll be able to quickly upload and download GBs of data and see how changes affect individual experiments.

If you need help with anything DVC or CML, make sure to
join our Discord community! We're always
answering questions and having good conversations with everybody that shows up.

Making Better Components With Storybook

Milecia — Thu, 30 Sep 2021 12:39:17 +0000

When you're working on large projects, it can help to have reusable components to handle the same functionality across different views. This saves time on writing code, makes it easier to maintain apps with many views, and can even lead to components that are usable in different projects.

There are a few different ways to do this and we'll be taking a look at component-driven development and one of the tools you can use to help with that.

Quick background on component-driven development

Component-driven development is when you create independent components. So your components aren't tied to any particular data, APIs, or other functionality. They can stand alone on their own and you work with them however you need at the time.

Some common components you'll see created like this include dropdowns, buttons, and containers. Building your components independently of each other can help you model your system better because you can drop in the pieces you need.

You'll even be able to write better tests for your apps because you can test components with more simple mock data. It also makes it clearer to find issues since you can test everything in isolation.

Where Storybook comes in

This is where a tool like Storybook comes in. It lets you develop your components in isolation from the rest of the app. That means you can test components without connecting to a server or running all of the functionality in the app.

Storybook starts up its own process to let you interact with components and demonstrate how components should work. Something else it helps with is the documentation for your apps.

You'll be able to add descriptions for props that are passed to components, explain how the component changes under different conditions, and check for accessibility issues.

Generating a Redwood app

Now that you know a bit about component-driven development and Storybook, let's see how it actually works. We'll do this with a new Redwood app since it comes with Storybook integration by default.

You can make a new app by running the following command:

yarn create redwood-app storybook-component

This will make a new Redwood project with several files and directories generated for us. While our focus will be in the web directory, it's good to note that the api directory is where your database connection and GraphQL server will live.

A new page

The front-end is where we'll be focused, so let's start by adding a new page to the app. Run the following command:

yarn rw g page display /

This creates a new page called DisplayPage in the web > src > pages directory. We'll use this page to display a video to the user, kind of like if they went to a page on YouTube.

Before we add the video component, let's take a look at what we have in Storybook just from our Redwood commands. So we'll start up Storybook with:

yarn rw storybook

This should start up Storybook and you should see something like this in the browser.

If you look in web > src > pages > DisplayPage, you'll see the DisplayPage.stories.js file. This is the type of file Storybook will be looking for to render individual components. The Storybook page will render the DisplayPage component exactly like it's written. Here's what the story page should look like.

import DisplayPage from './DisplayPage'

export const generated = () => {
  return <DisplayPage />
}

export default { title: 'Pages/DisplayPage' }

A couple of things to note for the stories.js file.

The name of the exported component is generated and that's the title of this particular view in the story. This name could be anything else you see fit. We'll go into more detail on story views in just a bit.
The title that's part of the export is how components and different views are grouped in Storybook. The directory format defines the group name and the component name for the tab in that group.

Redwood generates this basic file by default so all we have to do is update it.

To get a better feel for writing stories, let's make a component for the video that gets shown to the user.

Making a new component

We'll run the following command to create the video component:

yarn rw g component video

This command will create three new files in the web > src > component directory. We have the Video.js file that holds the actual video component. Then there's the Video.stories.js file that holds the Storybook story. Lastly, there's the Video.test.js file that holds the tests for this component.

Let's modify the existing code to render a video element with several props that are passed in. So in web > src > component > Video.js, you can delete the existing code and paste the following:

const Video = ({ videoSrc, width, height, controls }) => {
  return (
    <video width={width} height={height} controls={controls}>
      <source src={videoSrc} type="video/mp4" />
      Your browser does not support the video tag.
    </video>
  )
}

export default Video

This is where the beauty of Storybook comes in. We're not going to worry about adding this component to the DisplayPage while we're developing it. We're going to use the story page to test and document how the Video component works.

Updating the story

Since we have the Video component ready to play with, we can switch over to the Video.stories.js file and start writing new pieces to the story.

The first thing we'll do is update the generated view. We'll rename it to index because it will act as the starting point for working with the Video component and it'll have more documentation than the other views we'll add.

export const index = () => {
  return (
    <>
      <p>There are several props used in this component.</p>
      <div>
        width: sets the width of the video component
      </div>
      <div>
        height: sets the height of the video component
      </div>
      <div>
        videoSrc: sets the width of the video component
      </div>
      <div>
        controls: sets whether the video controls are shown or not
      </div>
      <Video width="320" height="240" videoSrc="https://res.cloudinary.com/milecia/video/upload/v1606580790/elephant_herd.mp4" controls={true} />
    </>
  )
}

Here, we've defined the props that are passed into the Video component and we have an example of the component in use. If you check back in the browser, you should see something like this.

Many times you'll have different use cases for the same component and Storybook can help you look at those individually as well. To handle passing props to different use case views, we have to introduce args into our story. We'll do that by adding the following template in Video.stories.js.

const Template = args => <Video {...args} />

This will let us pass different props to the Video component for each view we make. We'll make a default view, a large view, and a view with no controls. Add the following code below the index view we made earlier.

export const Default = Template.bind({})
Default.args = {
  controls: true,
  height: "240",
  width: "320",
  videoSrc: "https://res.cloudinary.com/milecia/video/upload/v1606580790/elephant_herd.mp4"
}

export const Large = Template.bind({})
Large.args = {
  controls: true,
  height: "840",
  width: "1020",
  videoSrc: "https://res.cloudinary.com/milecia/video/upload/v1606580788/sea-turtle.mp4"
}

export const NoControls = Template.bind({})
NoControls.args = {
  controls: false,
  height: "560",
  width: "840",
  videoSrc: "https://res.cloudinary.com/milecia/video/upload/v1606580790/elephant_herd.mp4"
}

We're using Cloudinary to store the videos and getting a URL to use as the source for the Video component to keep things simple. You can set up a free account and upload your own videos if you want to see something more interesting.

We're binding the view to the Template we created and that's how we're able to see them in the browser. You should see something like this now.

Finished code

You can take a look at the stories for the Video and DisplayPage components in this Code Sandbox or you can clone the whole project from the storybook-component directory in this repo.

Conclusion

Developing components in isolation from the complete app can make it easier to catch bugs before they become issues and it can help give developers a better understanding of how the whole system works.

Configuring Storybook in an existing project doesn't require much time, but it's a nice integration that already comes with Redwood. Whether you're working with multiple projects that depend on the same set of components or you're working with one large app that has a lot of components, using Storybook can help you with long-term maintenance and onboarding new engineers.

Adding Custom Branding to a User App

Milecia — Tue, 14 Sep 2021 13:13:53 +0000

Many organizations want some ability to use a service to handle some of their functionality and customize the interface users are shown. This includes things like the names they see displayed, data they want to be shown, or some images they want to see. Giving them the ability to add their own branding is one way to add value to your own products.

In this Redwood tutorial, we'll make an app that will change formats depending on what user is associated with the page.

Create the Redwood app

First thing we need to do is spin up a new app. In a terminal, run:

yarn create redwood-app branding

When this is done, you'll have a bunch of new files and folders in a branding directory. The main folders we'll be working in are the api and web folders. We'll start with some work in the api folder first.

Setting up the model

Building our app by making the models for the database schema works really well in Redwood. I usually like to start here because it's one way you can start thinking about your business logic from the beginning.

We'll be using a Postgres database. Here are the docs to get Postgres installed locally. Let's start by updating the .env file with a connection string for your local instance. Uncomment the DATABASE_URL line and update the value. It might look something like this.

DATABASE_URL=postgres://admin:password@localhost:5432/branding

Now we can go to api > db and open the schema.prisam file. This is where we'll add our models. One thing we need to do is update the provider value at the top to postgresql instead of sqlite. Next, you can delete the existing example model and add these.

model User {
  id     Int      @id @default(autoincrement())
  name   String
  info   Info[]
  image  Image[]
  layout Layout[]
}

model Image {
  id     Int    @id @default(autoincrement())
  name   String
  url    String
  user   User   @relation(fields: [userId], references: [id])
  userId Int
}

model Info {
  id        Int      @id @default(autoincrement())
  balance   Float
  lastLogin DateTime
  endDate   DateTime
  user      User     @relation(fields: [userId], references: [id])
  userId    Int
}

model Layout {
  id           Int    @id @default(autoincrement())
  name         String
  dataLocation String
  imageUrl     String
  user         User   @relation(fields: [userId], references: [id])
  userId       Int
}

Usually, when you have relationships between tables like we have here, it's a good idea to seed your database with some initial values. You'll see this pretty often with apps that have dropdown menus or pre-defined user roles.

We'll be adding our own seed data in the seed.js file. You can open that and delete all of the commented-out code in the main function and replace it with this.

await db.user.create({
  data: { name: 'Nimothy' },
})

await db.image.create({
  data: {
    name: 'Nimothy Profile',
    url: 'https://res.cloudinary.com/milecia/image/upload/v1606580774/fish-vegetables.jpg',
    userId: 1,
  },
})

await db.info.create({
  data: {
    balance: 7.89,
    lastLogin: new Date(),
    endDate: new Date(),
    userId: 1,
  },
})

await db.layout.create({
  data: {
    name: 'MidLeft',
    dataLocation: 'mid-left',
    imageUrl:
      'https://res.cloudinary.com/milecia/image/upload/v1606580774/fish-vegetables.jpg',
    userId: 1,
  },
})

Run migration

With our models and seed data in place, we can migrate the database with this command:

yarn rw prisma migrate dev

That will add the tables and columns with the defined relationships to your Postgres instance. To seed the database, we'll need to run:

yarn rw prisma db seed

This will add the placeholder data we created in seed.js so that the relationships between tables and columns are met and don't cause errors with our app.

Since we've run the migration and seeding, we can move on to the back-end and front-end.

Making the back-end and front-end

We're going to make the functionality to add new layouts and new users to the app for now so that we can show how things update for the user. We'll also be adding a special page to show how these updates would actually affect users.

For the sake of this project, we're going to assume that adding new users and layouts is admin functionality that users of the app won't be able to see. Later on, we'll add the user view that applies the custom branding.

Adding the ability to create and update users and layouts only takes a couple of commands in Redwood. Let's start by making the users functionality with this:

yarn rw g scaffold user

This will generate the back-end GraphQL types and resolvers as well as adding new components to the front-end. We'll run this command one more time for the layouts functionality:

yarn rw g scaffold layout

You can take a look at the code Redwood generated to make all of this work on the front-end by going through the web > src directory. There are new files under components, layouts, and pages, plus Routes.js has been updated. All of the new files you see were created by that scaffold command for those two models.

The back-end code that supports new user and layout creation and the edit and delete functionality can be found in the api > src directory. You'll see new files under graphql and services that hold the GraphQL types and resolvers that make all of the CRUD work and persists the data.

Now we have the CRUD for the front-end and back-end for these two models. You can run the scaffold command to create the CRUD for the other models, but we don't actually need it. What we do need are the types for those models. We can generate those with a couple of Redwood commands:

yarn rw g sdl info
yarn rw g sdl image

The sdl generator makes all of the GraphQL types and a resolver for the specified model. If you check out api > src > graphql, you'll see the new types that were generated for info and images. Then if you look in api > src > service, you'll see that a resolver has been made to handle a query for us for both info and images.

The reason we're adding these types is so the user types reference these so we need them to be available, even if we aren't adding the front-end piece.

Running the updated app

If you run your app with yarn rw dev and navigate to localhost:8910/users, you'll see a table and buttons for different ways to interact with the data. You should see something similar to this:

Go ahead and add a new user by clicking the "New User" button. This will open the form like this:

Now you can add a new layout for this new user by going to localhost:8910/layouts and clicking the "New Layout" button. It'll bring up this form:

Show the user their custom view

Now that we've got the core functionality together to create users and associate layouts with them, we can create the custom view that they will see. To do that, we'll use Redwood to generate a page that will load a specific user's layout. Make a new page with this command:

yarn rw g page option

This will add a new page to the web > src > pages directory and it will update the Routes.js file with a new /option route. If you navigate to localhost:8910/option, you'll see this:

We need to update this page to show the user's layout by pulling some data from the back-end.

Querying for the user layout

In the web > src > pages > OptionPage directory, open the OptionPage.js file and add the following import to get your GraphQL query ready.

import { useQuery } from '@redwoodjs/web'

Then at the bottom of the file, right above the export statement, add this code for the query.

const LAYOUT = gql`
  query layout($id: Int!) {
    layout(id: $id) {
      id
      name
      dataLocation
      imageUrl
      userId
    }
  }
`

This will give us a specific layout based on the id we pass to the query. We'll be manually setting this id to mimic what we might get from a prop from a different component. We'll add the variable for the id in our query hook. This will be added inside of the OptionPage component:

const { loading, data } = useQuery(LAYOUT, {
  variables: { id: 1 },
})

if (loading) {
  return <div>Loading...</div>
}

We're using the useQuery hook to execute the query we made earlier and we're manually setting the id of the layout we want to use. Then we're checking the load status for the data and rendering an indicator that the page is loading the content so that the user doesn't see an error before the fetch finishes.

The last thing we'll do is update the elements to show in the layout format we currently have loaded.

Updating the page

To show the right layout, we're going to install the styled-components package. That way we'll be able to pass props to update the layout based on the user viewing the page. So in the web directory in your terminal, run:

yarn add styled-components

Now we're going to import that package in the OptionPage.js file.

import styled from 'styled-components'

Then we need to add a new styled component to handle the location of the image based on that user layout. We'll add this right above the OptionPage component.

const Img = styled.img`
  display: block;
  position: absolute;
  top: ${(props) => (props.dataLocation === 'mid-left' ? '35%' : 'unset')};
  right: ${(props) => (props.dataLocation === 'mid-left' ? 'unset' : '0')};
  width: 360px;
`

We're doing a simple update of the image location with an absolute position setup. This will let the image move independently of the other elements on the page so that the user sees it in the place they've selected. We're passing in the dataLocation value as a prop.

Cleaning things up

Just a few finishing touches and we'll have this layout working. First, we need to add the Img to OptionPage. We'll delete the existing Link from the return statement and add this image instead.

<Img src={data.layout.imageUrl} dataLocation={data.layout.dataLocation} />

We'll also add a little line to show the name of the current layout. This will go below the description of the file location.

<p>{data.layout.name}</p>

That's it! We've finished up this app. Now if you run the app with yarn rw dev, you should see something similar to this.

If you update the id in the query variable to 2 and reload the browser, you'll see something like this.

Finished code

If you want to check out the complete code, you can check it out in the custom-app-branding folder of this repo. You can also check out the front-end in this Code Sandbox.

Conclusion

If you're interested in a deeper dive on how Redwood handles scaffolding or the general way it creates files for you, make sure to go through their docs.

Building a Drawing Board with Redwood

Milecia — Wed, 01 Sep 2021 13:20:35 +0000

Sometimes you just want to be able to draw pictures to describe things and send them to others quickly. You don't want to use a whole service or deal with specific tools, you just want to hand draw a thing and send it. That's what we're going to make in this Redwood tutorial.

We'll make a drawing board app that saves drawings to a Postgres database so users can quickly download their drawings as images.

Setting up Postgres locally

Since we'll be working with a Postgres database, let's start by making a local instance we can connect to. You can download Postgres here for the OS you're working on.

While you're going through the initial set up, pay attention to the user name and password you create. You'll need those for the connection string in Redwood.

Setting up the Redwood app

Now go to a terminal and run:

yarn create redwood-app drawing-board

This will create a new Redwood app with a bunch of directories and files. Feel free to check everything out, but we'll focus mainly on the api and web directories. One quick thing we need to handle is updating that database connection string.

Inside the .env file, uncomment the DATABASE_URL line and change it to match your local instance. That might look something like:

DATABASE_URL=postgres://postgres:admin@localhost:5432/drawing_board

This will be referenced in the schema.prisma file we'll be updating, but as a sneak peek, here's where it's used. You don't have to change anything here.

datasource db {
  provider = "postgresql"
  url = env("DATABASE_URL")
}

We'll need this in place so that the back-end of the app can communicate with the database.

Making the models

Let's write the model for the table that will hold the images. In api > db, open schema.prisma and the first thing we'll update is the provider value. This should be postgresql instead of sqlite.

Next, we'll remove the example user model from the file and replace it with our own. This model will represent the data we want to store for each canvas image we capture.

model Capture {
  id   Int    @id @default(autoincrement())
  name String
  url  String
}

All we're doing is storing a name and URL string for the image. We'll be storing a data url for the image in Postgres, but this could also be a link to an online storage service like AWS or Cloudinary.

Run the migration

Since this is the only model we'll have for this app, it's safe to run the migration now:

yarn rw prisma migrate dev

You'll be prompted to give the migration a name, but everything else happens automatically. Now that the database is set up, we'll start working on the back-end.

Making the back-end

Redwood uses GraphQL to handle everything in the back-end. So we're going to need some types and resolvers to let the front-end make request and get the data to the database. We'll run this command to generate some types and resolvers for us based on the Capture model.

yarn rw g sdl capture

Redwood creates new folders and files that have the GraphQL types in api > src > graphql and a query resolver in api > src > services for the Capture model. Now we just have to modify a few things.

Adding the create mutation for captures

We need to add new type to give us the ability to save captures from the drawing board to the database. Then we'll have to add the resolver that will actually add the data to the database.

First, we'll go to the captures.sdl.js file in the api > src > graphql directory. We're just going to add a new mutation type below the UpdateCaptureInput.

type Mutation {
  createCapture(input: CreateCaptureInput!): Capture!
}

This will make the request accessible from the front-end. Next we'll go to the captures.js file and add the mutation that persists the data to the database right below the query.

export const createCapture = ({ input }) => {
  return db.capture.create({
    data: input,
  })
}

We have a fully functioning GraphQL server right now! In fact, if you run the app with yarn rw dev and go to http://localhost:8911/graphql in your browser, you'll see the GraphQL explorer with the mutation we just added.

Making the front-end

Since we have the back-end working, it's finally time to build the front-end. We'll have a canvas on the page that let's use capture the drawing with a button click. At the bottom of the page, we'll have small views of the existing captured drawings.

The drawing board

Let's start by making a page for the drawing board. We'll take advantage of another Redwood command for this.

yarn rw g page capture /

This generates the page component, a Storybook story, and a Jest test for the component. It'll also automatically add the route for the new page to Routes.js. This page will point be at the base URL of the app, which is why we have the / int the page creation command above.

We also need to install the fabric package so that we can work with the canvas. In a terminal, go to the web directory and run:

yarn add fabric

Make sure you go up one directory level in your terminal after this! That way you'll be running the commands in the right place.

Then we'll go to web > src > pages > CapturePage and edit the CapturePage.js file. You can delete everything inside of the CapturePage component because we won't be using any of it. Let's import a few things first.

import React, { useState, useEffect } from 'react'
import { fabric } from 'fabric'

Next, we'll add a new state to the CapturePage component that will initialize the canvas object for us so that we can draw and save images.

const [canvas, setCanvas] = useState('')

useEffect(() => {
  setCanvas(initCanvas())
}, [])

const initCanvas = () =>
  new fabric.Canvas('capture', {
    height: 500,
    width: 500,
    backgroundColor: '#F6F6F6',
    isDrawingMode: true,
  })

The initCanvas sets up a new instance of the fabric canvas object and it's targeting a canvas element with an id of capture. Then we've given it some dimensions to limit the size on the page. It has a background color so that users know that's it's a different element to interact with. Lastly, we have drawing mode enabled so users can draw on the canvas and we can save the drawing they make.

We use useEffect to initialize this canvas only when the page loads and we set the state so that we can access this canvas later.

We'll add the canvas element inside a fragment in the return statement.

return (
  <>
    <canvas id="capture" />
  </>
)

If you run the app now with yarn rw dev, you'll see something like this in your browser.

Saving drawings

Next we need to add that button to trigger the save action. We'll need to add another import so we can use our GraphQL create mutation.

import { useMutation } from '@redwoodjs/web'

Then we'll need to write the definition of the GraphQL request we want to make. Below the import we just added, write the following:

const CREATE_CAPTURE_MUTATION = gql`
  mutation CreateCaptureMutation($input: CreateCaptureInput!) {
    createCapture(input: $input) {
      id
    }
  }
`

This defines the createCapture mutation we'll use to save the drawings. Now that we have the definition, we need to create the mutation request. Inside of the CapturePage component, just above the capture state, add:

const [createCapture] = useMutation(CREATE_CAPTURE_MUTATION)

Using this hook gives us access to a function we can call for this mutation. Now we should define a method that gets called when the save button is clicked. Below the initCanvas call, add this:

const saveCapture = () => {
  const imageUrl = canvas.lowerCanvasEl.toDataURL()

  const input = {
    name: `Capture${Math.random().toString()}`,
    url: imageUrl,
  }

  createCapture({
    variables: { input },
  })
}

If you take a look at the way Fabric handles canvases, there's an inner canvas that we want to get to we can save the drawing as an image. So once we have the right canvas, we get the data URL for the image and save it as part of the mutation input.

There are many better ways to make a random name for an image, but we're using a random number to give them unique names. Then we call the mutation with the input we just defined and it saves the drawing the database!

Displaying drawings

Just so you see that the drawings are actually there, scribble two or three things and save them. Now we'll add a query to get all of the images and show them in a flex element.

Let's start by adding a new hook to an existing import.

import { useMutation, useQuery } from '@redwoodjs/web'

Then we'll add a query for all the captures right below the mutation.

const GET_CAPTURES = gql`
  query {
    captures {
      name
      url
    }
  }
`

This will return an array with all of the captures we have in the database. We'll make this definition into something we can use inside of the CapturePage component.

const { data } = useQuery(GET_CAPTURES)

Lastly, we'll add an element that displays all of the returned captures. This can go right below the <canvas> element.

<div style={{ display: 'flex' }}>
  {data?.captures &&
    data.captures.map((capture) => (
      <img
        key={capture.name}
        style={{ padding: '24px', height: '100px', width: '100px' }}
        src={capture.url}
      />
    ))}
</div>

It maps over all of the captures and displays them as small images on the page. So you'll see something similar to this.

That's it! Now you can tweak this to have a sleek interface or a fancier way of storing images.

Finished code

You can check out the front-end in this Code Sandbox or you can look at the full code in the drawing-board folder of this repo.

If you check out the Code Sandbox, you'll notice the code is a little different. This is because we can't run a Redwood mono-repo with this tool, so an example of how the front-end works is what you'll see in the Code Sandbox. To get the full code, it's better to take a look at the repo on GitHub.

Conclusion

Since a lot of the things we do are virtual, it helps to have ways to still interface with the web that feels more natural. Drawing boards are becoming more popular so hopefully, this is helpful!