DEV Community: Directus

Migrating from Notion to Directus

Esther Adebayo — Mon, 27 Nov 2023 15:46:55 +0000

As a developer advocate and freelance coach, I share valuable content with my audience via my blog. When creating the blog, I needed a CMS that would integrate nicely with a Next.js Pages directory and make it easy to manage content. Notion was a great choice then, so I opted for it.

While Notion worked pretty well for most cases, the setup process wasn’t quite as easy as I expected, especially the process of mapping Notion elements to DOM elements.

I ran into some challenges and limitations.

Clunky SDK: Mapping Notion blocks to DOM elements required a lot of custom JS code
Field Relationships UX: Setting up relationships between page fields was quite cumbersome. For example, I couldn't easily connect blog posts to authors.

Workaround Solutions Within Notion

Based on the limitations, I had to come up with creative solutions:

Created a formatDate Function to show the latest publication date of a blog post.

const formatDate = (date: string) => {
  return new Date(date).toLocaleDateString('en-US', {
    year: 'numeric',
    month: 'long',
    day: 'numeric',
  });
};

Created a function to automatically add a slug for each blog entry using the slugify library.
Created a formatBlogData Function to match the Notion blocks to each content type.

export function formatBlogData(page: PageData) {
  const { properties = {}, id, cover } = page;

  const { Summary, Title, Published, Tags } = properties;

  const title = match(Title)
    .with({ type: 'title' }, (field) => field.title[0].plain_text)
    .otherwise(() => 'Untitled');

  const publishedDate = match(Published)
    .with({ type: 'date' }, (field) => field.date.start)
    .otherwise(() => '2023-01-01');

  return {
    id,

    title,

    slug: slugify(title).toLowerCase(),

    tags: match(Tags)
      .with({ type: 'multi_select' }, (field) => field.multi_select)
      .otherwise(() => []),

    coverImage: match(cover)
      .with({ type: 'external' }, (cover) => cover.external.url)
      .with({ type: 'file' }, (cover) => cover.file.url)
      .otherwise(() => ''),

    publishedDate: {
      raw: publishedDate,
      formatted: formatDate(publishedDate),
    },

    summary: match(Summary)
      .with({ type: 'rich_text' }, (field) => field.rich_text[0].plain_text)
      .otherwise(() => 'Placeholder summary'),
  };
}

Built a custom Notion block and text component to achieve the desired appearance for each content type.

These additional components and functions led to codebase complexity, and I soon realized there was a need for an alternative CMS that could offer scalability and maintainability over time.

Why Directus?

Today I am excited to share my recent adventure of migrating my blog content from Notion to Directus—a headless content management system (CMS). You may wonder, why Directus?

Well, Directus is not just another CMS. It offers a unique combination of flexibility, customization, and collaboration for content management. It also has built-in user roles and permissions and a JavaScript SDK which were core features I was particularly interested in.

💡 If you're new to Directus, create a Directus Cloud account here.

Creating the Blogs Collection and Data Model

Migrating my blog content to Directus was a smooth process. In my Directus instance, I initally created a blogs collection to hold all blog data. Then I went on to design the data model with the following fields:

id - Integer Input
status - Dropdown
title - Input
content - WYSIWIG
tags - Tags
authors - Many to Many relationship
image - Image
date_published - Datetime

Based on the data model created, I transferred the blog content from Notion to Directus.

Updating the Frontend Code

For seamless integration with Directus, I leveraged the power of the JavaScript SDK.
The first step involved installing it using the command:

npm install @directus/sdk

Subsequently, I eliminated the Notion-specific helper functions and code that pertained to content block handling. In the index.js file, using the Directus SDK, I fetched all blog posts, simplifying data fetching from Directus.

export const getStaticProps = async () => { 
  await directus.auth.static(process.env.DIRECTUS_TOKEN);

  const result = await directus.items('blogs').readByQuery({ sort: ['published_date'] });

  const resolvedResult = await Promise.all(
    result.data.map(async (blog) => {
      const author = await directus.items('Authors').readOne(1);
      return { ...blog, author: author?.name };
    })
  );

  resolvedResult?.forEach((blog) => {
    blog.image = `${process.env.DIRECTUS_URL}assets/${blog.image}`;
  });

  return {
    props: {
      blogs: resolvedResult,
    },
  };
};

By leveraging the WYSIWYG field in Directus, I could seamlessly handle the content of my blogs without the need for Notion components. Also, I no longer needed to rely on the formatDate function I had developed earlier, as Directus provides built-in sorting capabilities.

Image Handling

Directus proved to be a game-changer in terms of image handling. In Notion, images are stored as embedded assets. In Directus, images are stored as separate files. Each image in Directus is assigned a unique URL, facilitating seamless integration and effortless management.

Updating the Dynamic Route

Given that my project was built on Next.js, I made necessary modifications to the code, specifically targeting dynamic route data fetching. I also utilized the blog's ID as a slug for the blogs, eliminating the need for the Slugify library.

Here's the snippet showing the code used:

export const getStaticProps = async (context) => {
  const blogId = context.params?.blogId;
  const directus = new Directus(process.env.DIRECTUS_URL);
  const blog = await directus.items('blogs').readOne(blogId);
  blog.image = `${process.env.DIRECTUS_URL}assets/${blog.image}`;
  return {
    props: { blog },
  };
};

In Summary

With my blog content now securely hosted in Directus, I'm able to utilize more features of Directus and collaborate with other content creators and blog writers. I can:

Grant roles and permissions to collaborators, empowering them to share and contribute content effortlessly.
Enjoy live content previews without the need for application redeployment.

This project has been exciting, and I hope you have gleaned insights from this migration.

Directus and SEO: Tips & Tricks

Bryant Gillespie — Thu, 02 Nov 2023 04:01:00 +0000

Search engine optimization (SEO) is an ever-changing but super important part of getting your website in front of visitors.

When using Directus as a Headless CMS, it is incredibly un-opinionated about what you do with your data and content on the frontend, leaving how you build your website up to you.

But if you’re just starting out, being so open-ended can leave you wondering about the best way to handle things like SEO.

In this post, I’ll share a few tips for managing SEO with Directus. I’ll also share some links and resources for some of the most popular frontend frameworks.

Important Assumptions

You understand basic SEO strategy and terminology.
You’re familiar with collections, fields, and fetching data from Directus.

Create a Separate Collection for SEO Data

At the end of the day, page titles and meta tags are just data. And you have to store that SEO data for your pages and blog posts somewhere.

For simple sites, you could easily manage all your meta tag data by duplicating fields like title and meta_description from one collection to another.

But beyond a couple collections, this approach becomes cumbersome and potentially dangerous. What if you forget to copy one field? What if there’s a typo and the names become inconsistent? These oversights could break your SEO practices and ,at worst, your whole site.

One better option would be creating a single collection to standardize all the SEO data for your content collections:

Create an seo collection

seo

- id (Type: uuid)
- title (Type: String, Interface: Input, Note: This item's title, defaults to item.title. Max 70 characters including the site name.)
- meta_description (Type: Text, Interface: Textarea, Note: This item's meta description. Max 160 characters.)
- canonical_url (Type: String, Interface: Input, Note: Where should the canonical URL for this entry point to.)
- no_index (Type: Boolean, Interface: Toggle, Note: Instruct crawlers not to index this item.)
- no_follow (Type: Boolean, Interface: Toggle, Note: Instruct crawlers not to follow links on this item.)
- og_image (Type: Image, Note: This item's OG image. Defaults to global site OG image. The recommended size is 1200px x 630px. The image will be focal cropped to this dimension.)
- sitemap_change_frequency (Type: String, Interface: Input, Note: How often to instruct search engines to crawl.)
- sitemap_priority (Type: Decimal, Interface: Input, Note: Valid values range from 0.0 to 1.0. This value does not affect how your pages are compared to pages on other sites, it only lets the search engines know which pages you deem most important for the crawlers.)

Beyond the basic title and meta_description , the other fields you add to your SEO collection are totally up to you.

Adding the fields within Directus is only one half of the work - you need to use these fields in your frontend within your <head> tags and sitemap.

For each of your content collections that have a route on your frontend, inside Directus – create a many-to-one (M2O) relationship with the SEO collection.

When fetching your content on the frontend, use the fields parameter to expand the SEO data within a single API call.

import { createDirectus, rest, readItem } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());

const postId = '234ee-3fdsafa-dfadfa-dfada';

const post = await client.request(
    readItem('posts', postId, {
        fields: [
            'title',
            'summary',
            'content',
            'image',
            {
                seo: [
                    'title',
                    'meta_description',
                    'canonical_url',
                    'no_index',
                    'no_follow',
                    'og_image',
                    'sitemap_change_frequency',
                    'sitemap_priority',
                ],
            },
        ],
    }),
);

Then pass that to your frameworks specific method of add SEO metadata within your
tags.

Frontend Framework Metadata Documentation

Don’t Use Slugs as a Primary Key

The actual url for a page on your website is a key factor for search engine rankings. Because of that, your content editors will want to experiment and adjust urls and slugs for items as needed.

When adding a new collection Directus lets you choose from several types of primary keys for your collection.

Auto-incremented integer
Auto-incremented big integer
Generated UUID
Manually entered string

I’ve seen lots of folks name the primary key field slug and use the Manually entered string . It’s easy to understand. It makes fetching that item easier because you can get the item by its id (the slug) directly instead of constructing a query to match the slug.

But an item’s p*rimary key value can not be changed after they are created, while t*his protects your database and all of your relationships, it makes it hard to experiment or change URLs if, for example, a product name changes.

To avoid this, use the auto-incremented ids or UUIDs for the primary key id and create a separate field input for the slug . You can require uniqueness which means only one item in a collection can have a given slug.

You can no longer use API endpoints or SDK functions for reading a single item, as this relies on using the primary key. Instead, query the whole collection and use Filter Rules to get the single item that has the slug:

import { createDirectus, rest, readItems } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());

const slugFromYourFrontEndFramework = params.slug || router.query.slug // whatever your convention your framework follows;

const posts = await client.request(
  readItems('posts', {
    filter: {
      slug: {
        _eq: 'slugFromYourFrontEndFramework',
      },
    },
    limit: 1,
  })
);

const post = posts.data[0];

Use Relationships for Internal Linking

When building a website, you’ll need both links for internal content and links for external content.

One common pattern I’ve noticed is creating string inputs for internal links to other content.

But this can be surprisingly brittle. As soon as the slug for the Contact page changes from /contact-us to /contact-directus-team , the link will break and this can really crash your search engine rankings.

Luckily Directus makes a more dynamic approach possible with relationships.

When creating your data model for links to other items from the same or different collections, try using the conditional fields and many to one relationships to build a powerful, resilient way to link items.

Within your content collection, add the following fields for linking. (Note: This example is extremely simplified so you can learn the logic involved. - name these depending on what makes the most sense to you and your use case.)

your_content_collection

- link_type (Type: String, Interface: Dropdown, Note: Choices: [
    {
        "text": "Internal - Page",
        "value": "pages"
    },
    {
        "text": "Internal - Post",
        "value": "posts"
    },
    {
        "text": "External - URL",
        "value": "external"
    }
])
- link_label (Type: String, Interface: Input, Note: What label or title is displayed for this link?)
- link_page (Type: M20 Relationship, Related Collection: pages, Hidden On Detail, Conditions: [
    {
        "name": "IF link_type === page",
        "rule": {
            "_and": [
                {
                    "link_type": {
                        "_eq": "pages"
                    }
                }
            ]
        },
        "hidden": false,
    }
])
- link_post (Type: M20 Relationship, Related Collection: post, Hidden On Detail, Conditions: [
    {
        "name": "IF link_type === post",
        "rule": {
            "_and": [
                {
                    "link_type": {
                        "_eq": "post"
                    }
                }
            ]
        },
        "hidden": false,
    }
])
- link_external_url (Type: String, Interface: Input, Conditions: [
    {
        "name": "IF link_type === external",
        "rule": {
            "_and": [
                {
                    "link_type": {
                        "_eq": "external"
                    }
                }
            ]
        },
        "hidden": false,
    }
])

Fields for page, post, and external url are only visible when the related type is selected so there is no confusion about which fields to enter data for. And it also allows you to use that relationship to fetch the proper slug or permalink for posts and pages.

On the frontend, when you are fetching data via the API, use the [fields parameter](https://docs.directus.io/reference/query.html#fields) to get the related posts and pages in a single API call.

Then make sure you’re getting the proper url based on the link_type:

```tsx
const post = await client.request(
    readItem('your_content_collection', 'your_content_item_id', {
        fields: [
            // Fetch all the other root level fields for your collection **In production, you should only fetch the fields you need**
            '*',
            'link_type',
            'link_label',
            'external_url',
            // Use object syntax to fetch fields from a relation
            {
                page: ['id', 'title', 'permalink'],
                post: ['id', 'title', 'slug'],
            },
        ],
    }),
)

function getUrl(item) {
    if (item.link_type === 'pages') {
        return item.page.permalink ?? ''
    } else if (item.link_type === 'posts') {
        return `/blog/${item.post.slug}` ?? ''
    } else if (item.link_type === 'external') {
        return item.external_url ?? ''
    }
    return undefined
}

// ~~~ //
// Inside your template
// Make sure to use the correct syntax for your framework
<a href={getUrl(item)}>{item.link_label}</a>
// ~~~ //
```

Frontend Framework Link Documentation

Add Fields to Control Semantic Elements When Using Dynamic Page Builder

The structure of your content matters a lot for SEO. Crawlers like well structured pages with a clear hierarchy.

For educational items like blog posts or documentation, semantic hierarchy and design usually align well. Most of these items also have a well defined “template” or “layout” on the frontend.

The <h1> tag contains the title of the article and is the visually the largest header on the page. Other header tags like <h2> or <h3> get smaller visually and have less priority for SEO.

But for other items like that are more dynamic like landing pages or homepages, the Builder (Many To Any Relationships) really shine inside Directus. You can let your marketing or content teams build pages on their own with predefined collections or blocks without involving a developer at all. It also pairs beautifully with the Live Preview feature to allow them to see exactly what the site will look like before publishing.

However, handling the semantic markup you need for proper SEO versus the fact that blocks could be placed anywhere on a page can be a real challenge when developing your site.

Let’s take header tags for example. You need proper semantic hierarchy for SEO. But our hierarchy for SEO doesn’t always equal our visual hierarchy required for good design.

Having the keyword optimized <h1> tag be the largest visually - is not always ideal.

But in other cases, the <h1> tag should be the largest visually.

A great solution to this problem can be to create separate fields within the collection that allow the content editor to choose both the proper header tag and the visual size.

Here’s an example.

This provides a ton of flexibility. And with just a little training, editors can create pages that look great on screen and also perform well for SEO.

To render this on the frontend, you’d use dynamic components. Most frontend tools support the concept of dynamic components. The syntax will vary though so consult your frontend framework’s documentation.

Frontend Framework Component Documentation

Next.js - Dynamic Imports for Components
Nuxt - Dynamic Components
Astro - Components - Astro is a bit unique in that you can use components from other frameworks
[Svelte - svelte:component](https://svelte.dev/docs/special-elements#svelte-component)
Remix - I couldn’t find anything on dynamic components within Remix’s documentation.
Angular - Dynamic component loader

Implement a Sitemap

Sitemaps are important tools for crawlers like Googlebot to index your site properly. It’s easy to skip over this step when launching a new site, but it’s an important step that makes sure all the pages on your site can be found in search engines.

There’s not much to really manage inside Directus for a sitemap beyond properly creating your content collections. The heavy lifting for a sitemap is on the frontend.

Some frontend frameworks have an official or community-supported sitemap module / plugin. Others have instructions on how to generate a sitemap without the need to another package.

The exact implementation details will vary based on your selected framework but the general approach looks like this.

Create a function that fetches the items for each collection that has a route on your frontend.
Loop through those items formatting each as proper xml (or as the specific syntax your plugin requires).
Create a route like /sitemap.xml that returns the XML file.

Here’s an example that’s specific to Nuxt but the logic could be extracted to other frameworks.

```jsx
// This example is based on Nuxt and uses a third party package. 
// Consult your own frontend framework's documentation for how to properly generate a sitemap in their ecosystem.
// /server/routes/sitemap.xml.ts

import { SitemapStream, streamToPromise } from 'sitemap'
import { createDirectus, readItems, rest } from '@directus/sdk'

const directus = createDirectus(directusUrl).with(rest())

export default defineEventHandler(async (event) => {
    // Fetch all the collections you want to include in your sitemap
    const pages = await directus.request(
        readItems('pages', {
            fields: ['permalink'],
            limit: -1, // Be careful using -1, it will fetch all the items in the collection and could cause performance issues if you have a lot of items
        }),
    )

    const posts = await directus.request(
        readItems('posts', { fields: ['slug', { type: ['slug'] }], limit: -1 }),
    )

    // Create an array of objects with the url you want to include in your sitemap
    const urls = []

    urls.push(...pages.data.map((page) => ({ url: page.permalink })))

    urls.push(
        ...posts.data.map((post) => ({
            url: `/blog/${post.slug}`,
        })),
    )

    const sitemap = new SitemapStream({
        hostname: 'https://example.com',
    })

    // Add each url to the sitemap
    for (const item of urls) {
        sitemap.write({
            url: item.url,
            changefreq: 'monthly',
        })
    }

    sitemap.end()
    return streamToPromise(sitemap)
})
```

Frontend Framework Sitemap Resources

Next.js - XML Sitemap Documentation
Nuxt - Nuxt Simple Sitemap Module
Astro - @astro/sitemap Integration
Svelte - Sitemap Package
Remix - Remix SEO Package
Angular - I struggled to find a helpful tutorial or sitemap package for Angular.

Give Your Team Control of Redirects

It sucks having to pull yourself away from a fun (or important) project to manually add some redirects for a page. Do yourself a favor and let your content team add and manage redirects within the CMS.

Create a redirects collection

redirects

- id (Type: uuid)
- url_old (Type: String, Interface: Input)
- url_new (Type: Integer, Interface: Slider)
- response_code (Type: String, Interface: Dropdown, Choices: [
    {
        "text": "Permanent (301)",
        "value": "301"
    },
    {
        "text": "Temporary (302)",
        "value": "302"
    }
])

Add redirects dynamically when building your frontend. This is often done by creating a function to fetch the redirects from your Directus API and then passing those redirects to your frontend framework using a specific syntax inside a config file, plugin, or module.

// Though it depends on your specific framework, this logic would probably be called during build time
import { createDirectus, readItems, rest } from '@directus/sdk'

const directus = createDirectus(directusUrl).with(rest())

const redirects = await directus.request(readItems('redirects'))

for (const redirect of redirects) {
    let responseCode = redirect.response_code
        ? parseInt(redirect.response_code)
        : 301

    // If response code doesn't match what we expect, use 301
    if (responseCode !== 301 && responseCode !== 302) {
        responseCode = 301
    }

    // Add Logic here to add the redirects to a config file or tell your frontend framework how to handle them
    // ** Your Logic **
}

Frontend Framework Redirect Documentation

Don’t Forget Image Alt Text

Often overlooked, image alt text is important for SEO and critical for proper accessibility.

<img src="https://example.com/image.png" alt="An example image of how alt text works" width="500" height="500" />

A good way to manage image alt tags is on the files themselves as you upload them within Directus.

I prefer using the description field on files to store alt text. This way you don’t have to input alt text every single time you use this same image in different contexts.

For items like blog posts or articles you might have an image or featured_image field so you can have a nice hero image or a thumbnail if shown inside a card.

If you store alt text inside of the image item, you will want to fetch these nested title and description fields within the same API call:

const posts = await client.request(
  readItems('posts', {
    filter: {
      slug: {
        _eq: slugFromYourFrontEndFramework,
      },
    },
        fields: ['title', 'date_published', 'summary', 'content', { image: ['id', 'title', 'description']}]
    limit: 1,
  })
);

// ~~~ //
// Inside your template
<img src={post.image.id} alt={post.image.description ?? ""} />

Remember that the position of the image id will change from item.image to [item.image.id](http://item.image.id) when you fetch nested fields.

And remember – the actual alt text itself is just as important as rendering it on the page. I won’t dive into details because Moz has a great tutorial on how to write proper alt text here.

And if you’ve got 100s of images without alt text and you’re dreading doing all that work manually, try a boost from this extension - Directus Media AI Bundle - a winner in a recent AI Hackathon submitted by community member Arood. It uses several different AI tools to write image alt text or descriptions for you.

Frontend Framework Image Documentation

Next.js Images
Nuxt Images
Astro Images
Svelte Images
Remix - I couldn’t locate any documentation about images on the Remix site.
Angular Images

Summary

In this post, we’ve covered some SEO best practices when using Directus as a Headless CMS. Hopefully you’ve learnt something new, and can build more robust data models that serve both your users and search engine crawlers.

If these tips were helpful or if you have some of your own you’d like to share, let us know inside our Discord community.

Announcing the Directus Panel Quest Hackathon

Kevin Lewis — Mon, 09 Oct 2023 11:54:16 +0000

Following the success of the Directus AI Hackathon in August, we are today announcing a brand new contest for October. Directus Insights provides a fantastic canvas for helping people across your organization understand data. During Directus Panel Quest, we're challenging you to build new extensions to enhance and expand your dashboards.

Key Dates

Hackathon starts: October 4 2023 at 00:00 UTC.
Submissions end: October 31 2023 at 23:59 UTC.
Voting period: November 1 2023 until November 8 2023 at 23:59 UTC.
Winners announced: November 10 2023.

The Challenge

The Directus Insights Module is more powerful than many users realize. Data from your collections can be visualized to glean insights from your Directus project, but panels can do a lot more. You can display and visualize external data via API, or even build forms to interact with your data or external services.

The challenge of Panel Quest is to build new Panel Extensions that interact with or integrate with external services or data. Since Panels only run on the frontend, you should submit a bundle that includes any endpoints required to power your Panel.

Any external API or data will be accepted for this hackathon. Here are a few categories and ideas:

Communication APIs like Twilio, Vonage, Discord, and Slack
Marketing platforms like Salesforce, HubSpot, and Mailchimp.
Developer workflow tools like CircleCI, GitHub, and Vercel.
AI and Machine Learning APIs like OpenAI, Deepgram, and Replicate.
Payment and E-commerce platforms like Stripe, Shopify, and GoCardless.
Device and Browser APIs like sensors, location, and speech.

Submitting Your Project

To submit your project, you must:

Add your extension code to a public repository on GitHub.
Use our README template and replace anything in curly brackets with your submission's value.
Add the directus and directus-panel-quest topics (tags) to your GitHub repository.
Fill in this form to provide your email address so we can get in touch with the results.

We encourage all projects to include a LICENSE file in your repository with the Apache License 2.0, the GNU General Public License v3.0, or the MIT License.

The submission period ends on October 31 2023 at 23:59 UTC. You must complete all of the steps above by this time to be eligible. If you work with others, only one person must complete the steps.

Judging

On November 1 2023, we will curate all valid submissions into a blog post on the Directus Developer Blog with links to the last commit before the submission deadline (further commits will not be assessed).

Core Team Vote

This award is decided by the core team behind Directus. Each team member is given one vote to cast. When judging projects, we will look at the following criteria with no specific weighting:

Creative: Is the idea original and innovative?
Technical: How effectively do you integrate the external AP or dataI? Is the project well-executed? Does it run?
Relevance: Do you solve a real problem faced by people?
Presentation: Have you taken time to add polish to your project?

Judging will take place from November 1 2023 until November 8 at 23:59 UTC.

Community Vote

One of our prizes is decided by the community. From the valid submissions posted on our blog, the repository with the most GitHub Stars before the end of the judging period will win this category. No stars given or removed after the end of the judging period will be accepted.

The Prizes

Both the Directus Core Team and Community Vote prizes are the same:

$1000 USD awarded to the project submitter.
$250 USD donation to a charity of the winner’s choice from the following list:
- codebar - a charity that facilitates the growth of a diverse tech community by running free regular programming workshops for minority groups in tech.
- VetsInTech - who support transitioning military, veterans and spouses of either with reintegration services and by connecting them to the national technology ecosystem.
- Out In Tech - the world’s largest non-profit community of LGBTQ+ tech leaders.
- Carbon180 works toward developing equitable, science-based policies that will scale carbon removal.
- Cool Earth works with rainforest communities, tackles the root causes of deforestation, and protects vital carbon sinks.

Winners will be announced at a live Discord event on November 10 2023, and winners contacted over email on the same day.

Resources

We've created a few guides to get you started:

Create a Panel With Dynamic Form Based On Collection Fields shows you how to build dynamic user forms inside of panels, and create new items in your collections.
Create A Panel To Display External API Data With Vonage shows you how to visualize external data in your dashboards without needing to import data to Directus first.
Create An Interactive Panel To Send SMS With Twilio shows you how to build a polished and flexible panel that submits external POST requests.

We also have a few videos to show you how to create extensions:

This last one has an accompanying blog post: Using External Weather Data In A Custom Panel Extension

Additional Notes

Multiple submissions are allowed, and will be judged separately.
You own your projects - our incentive is to see the cool things people build.
We don’t handle prize-splitting, so if you’re working with others and win, we’ll send the prize to the Team Lead and they’ll be responsible for distributing it.
You can find the Terms & Conditions for this contest here.

Get Started

You can run Directus locally using Docker in just a few minutes

You can find educational resources here on the Directus Developer Blog, in our extension-building guides, and on our YouTube channel.

At any point during the hacking period, feel free to drop by our Discord server and ask for help, or ask questions about the hackathon in the #hackathon channel. We also have fortnightly Office Hours events on Thursdays which we’ll dedicate to the hackathon throughout October.

Using External Weather Data In A Custom Panel Extension

Kevin Lewis — Mon, 09 Oct 2023 11:51:27 +0000

In this post, you will learn how to fetch data from an external data source and display it in a custom panel extension for Directus Insights.

Panels can only talk to internal Directus services, and can't reliably make external web requests because browser security protections prevent these cross-origin requests from being made. To create a panel that can interact with external APIs, you will create bundle including an endpoint (that can make external requests) and a panel (that uses the endpoint).

Add an Extensions Volume

Follow our Directus Self-Hosted Quickstart, adding a volume for extensions:

volumes:
  - ./database:/directus/database
  - ./uploads:/directus/uploads
  - ./extensions:/directus/extensions // [!code ++]

Create a Bundle

Once you have run docker compose up for the first time, local directories for the volumes will be created. Navigate to the extensions directory and use the Directus Extensions CLI to create a bundle:

npx create-directus-extension@latest
├ type: bundle
├ name: directus-extension-bundle-weather
└ language: javascript

Then, navigate to the newly-created extension directory.

Create an Endpoint

Use npm run add to add a new extension to the bundle:

npm run add
├ type: endpoint
├ name: weather-endpoint
└ language: javascript

Navigate to the new weather-endpoint/index.js file and replace it with the following:

export default {
    id: 'weather',
    handler: (router) => {
        router.get('/', async (req, res) => {
            try {
                const response = await fetch(`https://api.open-meteo.com/v1/forecast?current_weather=true&${req._parsedUrl.query}`);

                if (response.ok) {
                    res.json(await response.json());
                } else { 
                    res.status(response.status).send(response.statusText);
                }
            } catch(error) {
                res.status(500).send(error.message);
            }
        })
    }
}

From the directus-extension-bundle-weather directory, run npm run build. Restart your Directus project, and you should now be able to access http://localhost:8055/weather?longitude=0&latitude=0.

The Open-Meteo API requires a longitude and latitude, so they must always be provided.

Create a Panel

Use npm run add to add a new extension to the bundle:

npm run add
├ type: panel
├ name: weather-panel
└ language: javascript

Navigate to the new weather-panel/index.js file, update the id to weather-panel and the name to Weather.

In the options array, remove the text field, and add two new fields for longitude and latitude:

options: [
    {
        field: 'longitude',
        name: 'Longitude',
        type: 'string',
        meta: {
            interface: 'input',
            width: 'half',
        },
    },
    {
        field: 'latitude',
        name: 'Latitude',
        type: 'string',
        meta: {
            interface: 'input',
            width: 'half',
        },
    },
],

Open panel.vue, and at the top of the <script>, import useApi and Vue's ref:

import { useApi } from '@directus/extensions-sdk'; // [!code ++]
import { ref } from 'vue'; // [!code ++]

export default {

Then, add longitude and latitude props:

props: {
    showHeader: {
        type: Boolean,
        default: false,
    },
    longitude: { // [!code ++]
        type: String,  // [!code ++]
        default: '0',  // [!code ++]
    },  // [!code ++]
    latitude: {  // [!code ++]
        type: String,  // [!code ++]
        default: '0',  // [!code ++]
    },  // [!code ++]
},

Create a setup method which will run when the panel is loaded:

setup(props) {
    const api = useApi();
    const weather = ref({});

    async function fetchData() {
        const response = await api.get(`/weather?longitude=${props.longitude}&latitude=${props.latitude}`);
        weather.value = response.data;
    }
    fetchData();

    return { weather };
}

This code will immediately fetch weather data using the new internal endpoint, and then make it available as weather to the template.

Finally, update the template:

<template>
    <div class="text" :class="{ 'has-header': showHeader }">
        {{ text }}  // [!code --]
        {{ weather }}  // [!code ++]
    </div>
</template>

Run npm run build from the bundle directory, and restart Directus.

Use the Panel

Create a new Insights Dashboard and add a Weather panel. Add coordinates, and you should see external data displayed in the panel.

You can now create panels using external data. If you have any questions at all, feel free to join our Discord community.

Co-founder of Nuxt joins Directus as its new Director of Engineering

Ben Haynes — Thu, 05 Oct 2023 13:48:12 +0000

Directus, the open source composable data platform, announced today that Alex Chopin, the co-founder of Nuxt.js, has joined the company in a strategic leadership role as their new Director of Engineering.

This move underscores Directus’ commitment to driving innovation in the open source space and strengthening its technical leadership.

"Adding Alex to our team is a move that not only enriches our technical leadership but also aligns seamlessly with our core mission of democratizing data,” said Ben Haynes, CEO and co-founder of Directus. “His open-source ethos resonates with our vision. We are extremely excited to have him continue his journey with us."

Alex, alongside his brother Sébastien, co-founded Nuxt six years ago.

What began as a side project to develop server-side rendered Vue applications, has since grown into one of the most popular frameworks in the web development space.

According to BuiltWith, Nuxt has powered close to 850,000 websites globally.

“When I started Nuxt with my brother Sébastien almost 7 years ago, I never expected to have such an incredible experience,” said Alex. "During that journey we also built NuxtLabs, a startup made of talented and passionate people with a vision of what the future web should look like.”

“But after six years as an open source company founder with all the ups and downs it brings, I decided it was time for another challenge. I am exhilarated to begin this new chapter with Directus.”

Directus, a composable data platform crafted in Typescript and Vue.js, piqued Alex’s interest with its mission to democratize the world's data, and also because of its strong roots in the open source community.

"Alex's expertise in Vue.js and his experience with community-driven projects will be instrumental in advancing our engineering objectives,” said Rijk van Zanten, co-founder and CTO at Directus.

“As a founder himself, he understands what it takes to build a product and a business into it's full potential. His innovative vision and perspective will be huge for our team as we continue to scale."

About Directus
Directus is the composable data toolkit and platform that allows developers, teams, and agencies to quickly build anything or everything. With over 26 million Docker downloads and 23,000 GitHub stars, it provides a robust toolkit and platform to turn any database into a headless data engine. Learn more at directus.io.

Building a User Feedback Widget with Vue.js and Directus

Bryant Gillespie — Fri, 22 Sep 2023 04:25:28 +0000

One of our DevRel initiatives at Directus is constantly improving our documentation. As a small team with finite time and resources, we rely a lot on user feedback to help guide our writing efforts. But we were missing the most important bit there – your feedback.

What We’re Building

At the time of this post, the Directus Docs runs on VitePress (which in turn is based on Vue.js and Vite). Vitepress is a nice bit of kit for quickly generating a static documentation site, but sadly there’s no built-in feature for gathering user feedback.

So I decided to build my own so our team could make better decisions on where to spend our precious time and attention.

While this project was built in the context of Vitepress, this post will show you how to do it with Vue generally. Here’s what our finished product will look like.

Prerequisites

Before we hop 🐰 in , here’s what you’ll need to follow along:

Knowledge

Beginner knowledge of Javascript, Typescript, and Vue.js (Composition API)

Tooling

A Directus instance up and running (either self-hosted or on Directus Cloud)
A Vue.js project set up (Using Vite is recommended)

Preparing Directus Collection

First off, we're going to need a place to store all this valuable feedback we'll be gathering.

Create a docs_feedback collection with the following data model:

docs_feedback

- id (Type: uuid)
- date_created (Type: Timestamp, Interface: Date/Time)
- url (Type: String, Interface: Input)
- rating (Type: Integer, Interface: Slider)
- title (Type: String, Interface: Input)
- comments (Type: Text, Interface: Textarea)

Creating Vue Component for Article Feedback

Just as if it were the lone dev on a cross-functional team – we’re going to place a lot of different responsibilities on our hard-working little Vue component.

Rating System: We’ll use a 1 to 4 scale, with each value associated with a different message. These messages will help engage users and guide them through the feedback process.
Open Ended Feedback: We provide a text area for users to write their thoughts. This is where the gold is. We want users to share their ideas, suggestions, and insights – positive or constructive 😭.
Posting Data to Directus: The component handles the submission of the feedback to Directus. It constructs the feedback object and makes a POST request to the feedback API endpoint.

Scaffolding the Feedback Component

Create a new file in our components directory named ArticleFeedback.vue . Then copy and paste the following code.

<script setup lang="ts">
</script>

<template>
    <div class="wrapper">
        <div class="step">
            <!-- Step 1. Show Rating Buttons -->
            <div>
                <p class="desc">How can we improve?</p>
                <p class="heading">How helpful was this article?</p>
            </div>
        </div>
        <div class="step">
            <!-- Step 2. Ask for Comments -->
        </div>
        <div class="step">
            <!-- Step 3. Show Success Message -->
        </div>
    </div>
</template>

<style scoped>
</style>

We’ve got three different states (or steps as I’m calling them) we’ll need to build.

An initial state that shows the feedback prompt and rating buttons.
Once a rating has been selected, a state which asks for comments and feedback.
A success state once form submission is complete.

Adding Props and Reactive Logic

Now let’s start adding our logic to control these three steps.

<script setup lang="ts">
+ import { ref, reactive } from 'vue';
+
+ const props = defineProps<{
+   title: string;
+   url: string
+ }>();
+
+ const feedback = reactive<{
+   id?: string;
+   rating?: number;
+   comments?: string;
+ }>({});
+
+ const success = ref(false);
</script>

<template>
    <div class="wrapper">
-       <div class="step">
+       <div v-if="!feedback.rating" class="step">
            <!-- Step 1. Show Rating Buttons -->
            <div>
                <p class="desc">How can we improve?</p>
                <p class="heading">How helpful was this article?</p>
            </div>
        </div>
-       <div class="step">
+       <div v-else-if="feedback.rating && !success" class="step">
            <!-- Step 2. Ask for Comments -->
        </div>
-       <div class="step">
+       <div v-else class="step">
            <!-- Step 3. Show Success Message -->
        </div>
    </div>
</template>

<style scoped>
</style>

Import the ref and reactive functions from Vue.
We’ll pass the url and page title as props from the parent component that contains this widget.
Create a reactive object feedback to manage our form submission data.
Create a reactive success variable to hold the success state.
Use v-if, v-else-if, and v-else to control what step of the feedback process is shown.

With the logic roughed in, let’s add our rating buttons.

Adding the Rating Options

<script setup lang="ts">
import { ref, reactive } from 'vue';

const props = defineProps<{ title: string; url: string }>();

const feedback = reactive<{
    id?: string;
    rating?: number;
    comments?: string;
}>({});

+ const ratingOptions = [
+   { label: 'Worst Doc Ever 🗑️', value: 1, message: 'Woof! 🤦‍♂️ Sorry about that. How do we fix it?' },
+   { label: 'Not Helpful 😡', value: 2, message: '🧐 Help us do better. How can we improve this article?' },
+   { label: 'Helpful 😃', value: 3, message: 'Nice! 👍 Anything we can improve upon?' },
+   { label: 'Super Helpful 🤩', value: 4, message: `Awesome! The whole team is rejoicing in celebration! 🥳🎉🎊 Anything you'd like to say to them?` },
+ ];
+
+ function getRatingOption(rating: number) {
+   return ratingOptions.find((option) => option.value === rating);
+ }
</script>

<template>
    <div class="wrapper">
        <div v-if="!feedback.rating" class="step">
            <!-- Step 1. Show Rating Buttons -->
            <div>
                <p class="desc">How can we improve?</p>
                <p class="heading">How helpful was this article?</p>
            </div>
+           <div class="button-container">
+                   <!-- We'll add a function for handling button clicks while adding our submission logic -->
+                   <button v-for="item in ratingOptions" :key="item.value" class="btn">
+                       <span>{{ item.label }}</span>
+                   </button>
+           </div>
        </div>
        <div v-else-if="feedback.rating && !success" class="step">
            <!-- Step 2. Ask for Comments -->
        </div>
        <div v-else class="step">
            <!-- Step 3. Show Success Message -->
        </div>
    </div>
</template>

The rating options will be an array of objects that have a visible label, a corresponding value of 1-4, and a dynamicmessage that we’ll display to encourage the user to leave comments after selecting a rating.

We’ll also create a small helper function to return the rating object based when passing a number value. This will come in handy in the second step because we’re going to display the rating the user chose.

Add a new div to Step 1 below the feedback prompt that will contain our rating options. Inside that, we’ll use v-for to loop through the ratingOptions array and render the individual buttons.

Asking for Comments

<template>
    <div class="wrapper">
        <div v-if="!feedback.rating" class="step">
            <!-- Step 1. Show Rating Buttons -->
            <div>
                <p class="desc">How can we improve?</p>
                <p class="heading">How helpful was this article?</p>
            </div>
            <div class="button-container">
                <button v-for="item in ratingOptions" :key="item.value" class="btn">
                    <span>{{ item.label }}</span>
                </button>
            </div>
        </div>
        <div v-else-if="feedback.rating && !success" class="step">
            <!-- Step 2. Ask for Comments -->
+               <div>
+                   <p class="desc">This article is</p>
+                   <div>
+                       <span>{{ getRatingOption(feedback.rating)?.label }}</span>
+                       <button class="btn" @click="feedback.rating = undefined">
+                           ❌
+                       </button>
+                   </div>
+               </div>
+               <p class="heading">{{ getRatingOption(feedback.rating)?.message }}</p>
+               <textarea v-model="feedback.comments" autofocus class="input" />
+               <button class="btn btn-primary" :disabled="!feedback.comments">
+                   Send Us Your Feedback
+               </button>
        </div>
        <div v-else class="step">
            <!-- Step 3. Show Success Message -->
+           <p class="heading">Thanks for your feedback!</p>
        </div>
    </div>
</template>

In Step 2 of the process, we’re showing the user the rating they chose using our getRatingOption helper function we created.

To improve the user experience, we’ll also let users go back and choose a different rating in case they picked the wrong one by mistake. Whenever they click the close button we’ll set the feedback.rating property to undefined which will take the user back to Step 1 based on the v-if logic we created.

Below that, we’ll show the proper message for the option they chose to encourage them to leave helpful comments in short form with a textarea input and a submit button.

We’ll also prevent them from submitting from Step 2 when the comments are empty, so we pass the :disabled="!feedback.comments" prop to the button element.

Adding Styling

Next, let’s add some basic styling.

// ^^ Rest of ArticleFeedback.vue Component ^^
<style scoped>

.wrapper {
    margin: 2rem 0;
    padding: 1.5rem;
    border: 1px solid rgba(60, 60, 67, .12);
    border-radius: 8px;
    background: #f6f6f7;
}

.step > * + * {
    margin-top: 1rem;
}

.desc {
    display: block;
    line-height: 20px;
    font-size: 12px;
    font-weight: 500;
    color: rgba(60, 60, 67, .75);
}

.heading {
    font-size: 1.2rem;
    font-weight: 700;
}

.button-container {
    display: grid;
    grid-gap: 0.5rem;
}

.btn {
    border: 1px solid solid rgba(60, 60, 67, .12);
    background-color: #ffffff;
    border-radius: 8px;
    transition: border-color 0.25s, background-color 0.25s;
    display: inline-block;
    font-size: 14px;
    font-weight: 500;
    line-height: 1.5;
    margin: 0;
    padding: 0.375rem 0.75rem;
    text-align: center;
    vertical-align: middle;
    white-space: nowrap;
}

.btn:disabled {
    opacity: 0.5;
}

.btn:hover {
    border-color: #6644ff;
}

.btn-primary {
    color: #fff;
    background-color: #6644ff;
    border-color: #6644ff;
}

.btn-primary:hover {
    background-color: #4422dd;
    border-color: #4422dd;
}

.input {
    width: 100%;
    height: 100px;
    border: 1px solid #ccc;
    border-radius: 4px;
    padding: 0.375rem 0.75rem;
}

@media screen and (min-width: 768px) {
    .button-container {
        grid-template-columns: repeat(4, 1fr);
    }
}
</style>

Adding Submission Logic Inside The Vue Component

We’re going to write a handler function to actually submit our data to our Directus docs_feedback collection.

At the end of our <script> tag, let’s add our submission handler.

async function handleSubmission(rating?: number) {
    loading.value = true;
    if (rating) feedback.rating = rating;

    const body = {
        id: feedback.id,
        rating: feedback.rating,
        comments: feedback.comments,
        title: props.title,
        url: props.url,
    };

    // Replace this with your own Directus URL
    const directusBaseUrl = 'https://yourdirectusurl.directus.app';

    try {
        let response;

        // If we've already created a feedback record, we'll update it with the new rating or comments.
        if (feedback.id) {
            response = await fetch(`${directusBaseUrl}/items/docs_feedback/${feedback.id}`, {
                method: 'PUT',
                body: JSON.stringify(body),
            });
        } else {
            response = await fetch(`${directusBaseUrl}/items/docs_feedback/${feedback.id}`, {
                method: 'POST',
                body: JSON.stringify(body),
            });
        }

        const data = await response.json();
        feedback.id = data.id;

        // If the reponse has comments, we can assume they've completed the second step. So we'll show the success message.
        if (data.comments) {
            success.value = true;
        }
    } catch (err) {
        error.value = err;
    } finally {
        loading.value = false;
    }
}

This function handleSubmission accepts an optional rating and then conditionally creates a new feedback item or updates depending on which step the user completed.

We also need to update our template to call our handler using the @click directive.

<template>
    <div class="wrapper">
        <Transition name="fade" mode="out-in">
            <div v-if="!feedback.rating" class="step">
                <div>
                    <div>
                        <p class="desc">How can we improve?</p>
                        <p class="heading">How helpful was this article?</p>
                    </div>
                </div>
                <div class="button-container">
                    <button v-for="item in ratingOptions"
                        :key="item.value"
                        class="btn"
+                       @click="handleSubmission(item.value)">
                        <span>{{ item.label }}</span>
                    </button>
                </div>
            </div>
            <div v-else-if="feedback.rating && !success" class="step">
                <div>
                    <p class="desc">This article is</p>
                    <div>
                        <span>{{ getRatingOption(feedback.rating)?.label }}</span>
                        <button style="margin-left: 0.5rem" class="btn" @click="feedback.rating = undefined">
                            <span mi icon>close</span>
                        </button>
                    </div>
                </div>
                <p class="heading">{{ getRatingOption(feedback.rating)?.message }}</p>
                <textarea v-model="feedback.comments" autofocus class="input" />
                <button
                    class="btn btn-primary"
                    :disabled="!feedback.comments"
+                   @click="handleSubmission()">
                    Send Us Your Feedback
                </button>
            </div>
            <div v-else class="step">
                <p class="heading">Thanks for your feedback!</p>
            </div>
        </Transition>
    </div>
</template>

Sweet! Now there’s just one last step before we have a working component.

Updating Permissions inside Directus

Right now, if we try to submit some feedback, we’re probably to going receive an Permission denied error from Directus.

This is because all collections have zero public permissions by default. While this is great for security, it’s not so great if we want to store our feedback data.

Open up the Public role with the Roles & Permission settings. Then scroll to find the docs_feedback collection.

Create and Update Operations

Click the block button inside each column and choose check All Access.

Read Operation

We might not want any prying eyes to be able to read the actual feedback ratings and content, so we’ll use some custom permissions to restrict the fields that anyone can ‘read’.

Click the button for the Read column, and choose Custom Permissions.

On the Field Permissions tab, check only the id field.

When you’re all done, it should look like this screenshot.

Awesome! Now on to testing.

Testing the Feedback Widget

Let’s open this up our Vue app and our Directus instance to test that everything is working as intended.

Make sure you check that the form submissions are correct inside Directus.

Next Steps

Here’s a few of the next steps you may want to explore beyond this tutorial.

Analyze the Data Using Directus Insights

Collecting feedback is just one half of the equation. Analyzing and taking action on the data you receive is the more important part.

Our module for creating no-code dashboards - Directus Insights - can help you understand the data you collect much easier and faster than browsing through a list of feedback.

Secure form submissions

To post our form submissions, we just enabled Public create and update access for the docs_feedback collection inside Directus.

There’s not a lot to gain by spamming documentation feedback submissions but you never know with folks these days.

Security wise - we could do better.

Here’s a few options:

Create a Flow with using an incoming webhook trigger that processes the incoming requests.
Obscure our Directus instance URL by using a proxy or serverless function to make the call to the Directus API. Netlify, Vercel, and other hosting static site hosting platforms simplify this process.

Add a session identifier to track feedback from the same user

It could be very handy to know if feedback across different articles is coming from the same user. We don’t really need full blown user sessions stored in the database for this. We could implement it client-side by:

adding a field to for session_id or visitor_id to our collection inside Directus
generating a random ID on a first visit or feedback submission inside the Vue app
storing the ID within the browser using localStorage or sessionStorage
grabbing that ID and passing it in the API call to Directus

I hope you find this post useful - if you have any questions feel free to join our Directus Discord server.

Detecting High-Risk Phone Numbers with Vonage and Directus Automate

Kevin Lewis — Tue, 19 Sep 2023 09:32:37 +0000

When creating new users for your service, it's important to take steps to prevent fraudulent or malicious activity. In this post, you'll use Vonage's Number Insight V2 API and Directus Automate to determine the likelihood of a number being risky at the time of user registration, and let you act on it.

The Vonage Number Insight V2 API assigns a fraud score to numbers, along with a risk recommendation - allow, flag, or block. You can use this recommendation to allow user creation, allow it with a note to your team to validate or block creation.

Before You Start

You will need a Directus project - check out our quickstart guide if you don't already have one. You will also need a Vonage Developer API account, taking note of your API Key and Secret. You should also have a high-risk number to test with (I used the last spam caller I had).

Finally, in Your Directus project, add an input field called phone_number to the directus_users collection. This is a system collection, so you will need to expand them in the Data Model settings in order to see the directus_users collection.

Set Up Trigger

Create a new Flow from your Directus project settings - call it "Check Phone Fraud Risk". Create an Event Hook trigger that is Blocking - this means the flow will run before the data is entered in the database. Set the Scope to items.create on the directus_users collection - this means the flow will start whenever a new user is created.

Set Up Number Insight Check

When authenticating your Vonage API call, you must provide your API Key and Secret Base64-encoded. Find an online encoder, and encode the following your_key:your_secret (the colon is important). Take note of the encoded string.

Create a Webhook / Request URL operation and set the Key to check_number. Setting the key inserts the data into the Flow's data chain using this property name. Set the Method to POST and the URL to [https://api.nexmo.com/v2/ni](https://api.nexmo.com/v2/ni).

Set one header:

Authorization: Basic BASE_64_ENCODED_AUTH_STRING

In the body, send the following JSON:

{
   "type": "phone",
   "phone": "{{$trigger.payload.phone_number}}",
   "insights": ["fraud_score"]
}

Navigate to the Users Module in the module bar and create a new user. You can leave all information blank apart from the phone number - make sure it's in E.164 format. If you need to format numbers, check out a section in our post on building a wedding invite system - it also uses a Vonage API so you can reuse your credentials.

Come back to your flow and open the logs in the sidebar. You can see the operation outputs an object containing a fraud_score and related information. The risk_score is a scale of 0 to 100. This project will use the risk_recommendation value of allow, flag, or block in future steps.

Set Up Conditionals For Fraud Recommendation Result

From the resolved path of the API request, create a Condition operation with the following rule:

{
    "check_number": {
        "data": {
            "fraud_score": {
                "risk_recommendation": {
                    "_eq": "allow"
                }
            }
        }
    }
}

The resolved path will be followed if the risk_recommendation is allow. If a flow ends on a resolved path, the Blocking Flow will end and the item will be added to the collection.

The reject path will be followed if the value is anything else. From the reject path, create another Condition operation to determine whether the recommendation is flag or block:

{
    "check_number": {
        "data": {
            "fraud_score": {
                "risk_recommendation": {
                    "_eq": "flag"
                }
            }
        }
    }
}

The resolved path will be flag, and the reject path will be block.

The flow now looks like this:

Send Emails If Flagged or Blocked

In this tutorial, a flagged user will still be created, but an email will be sent to an internal team member to perform manual validation. From the resolved path of Is Flagged create a Send Email operation. Add an email address, and inject dynamic values in the Subject and Body:

— Subject —

Flagged Phone Number from {{$trigger.payload.first_name}} {{$trigger.payload.last_name}}

— Body —

The phone number {{$trigger.payload.phone_number}} was flagged by the Vonage Number Insight system with a score of {{check_number.data.fraud_score.risk_score}}. 

Please manually validate this user's profile before approving their jobs.

Reject New User Item If Blocked

From the reject path of Is Flagged create a Send Email operation. Form a rejection message and send it to the user who tried to register using {{$trigger.payload.email}} as the recipient.

When a Blocking Flow concludes, data is entered into the database. Currently, there is no elegant way to stop this, but there is a reliable way to make this happen. After the email operation that sends the rejection, create a Run Script operation from the resolved path:

throw new Error('Phone number failed fraud checks');

This will cause the Flow to fail and not enter the item into the directus_users collection.

Your final flow should look like this:

Summary

In this post, you have learned how to use the Vonage Number Insight V2 API to check a phone number for the likelihood of fraud at the time of new user registration. Based on the outcome, users are created, flagged, or blocked from being created.

Based on the allow, flag, or block recommendation, you can add any operations from those provided by Directus, or through building your own.

If you have any questions, please feel free to join our Discord server and ask them.

Building a Job Board with Next.js, Chakra UI, and Directus

Esther Adebayo — Wed, 13 Sep 2023 10:23:14 +0000

Job boards are an ideal way to connect job seekers to career opportunities. However, creating one involves far more than putting up postings. As developers, we need to incorporate essential features like job listing management, search functionality, and more.

A well-designed job board allows employers to effortlessly post and manage job openings. It also enables job seekers to browse through jobs using intuitive filtering and searching.

In this tutorial, we will cover the development of the core components of a job board step-by-step, using Next.js for the frontend and Directus as the backend tool to manage job data.

Here's a quick overview of how the job board looks to job seekers:

TL;DR: If you'd like to immediately access the code repository, get it here

Prerequisites

To follow along with this tutorial, you need to have the following:

A Directus self-hosted or cloud account
Familiarity with TypeScript, React and Next.js
Basic knowledge of Chakra UI - a React component library.

Setting up the Jobs Collection in Directus

Before we can start fetching and displaying job listings, we need to define the data model that will store our job data in Directus.

Log in to your Directus app and navigate to Settings > Data Model. Click the + icon to create a new collection called “jobs”.

Add the following fields and save:

title (Type: String, Interface: Input)
company (Type: String, Interface: Input)
location (Type: String, Interface: Input)
logo (Type: UUID, Interface: Image)
tags (Type: JSON, Interface: Tags)
remote (Type: Boolean, Interface: Toggle)
datePosted (Type: DateTime, Interface: DateTime)
salaryRange (Type: String, Interface: Input)
content (Type: Text, Interface: WYSIWYG)

Adding Content to the Jobs Collection

With the data model in place, we're now ready to populate our collection with some real job listings.

From the Directus sidebar, navigate to "Content Module" and select the "Jobs" collection we created earlier.

Go ahead and add a few sample jobs to have content to work with as we build out the frontend interface. You can always come back later to enter more postings as needed.

Building the Frontend Application

With the backend in place, we need to set up a working frontend interface to display the job listings.

Installing Next.js

In your terminal, run the following command:

npx create-next-app@latest job-board

cd job-board

On installation, choose the following:

Would you like to use TypeScript? Yes
Would you like to use ESLint? Yes
Would you like to use Tailwind CSS? No 
Would you like to use `src/` directory? Yes
Would you like to use App Router? (recommended) No
Would you like to customize the default import alias?  Yes
What import alias would you like configured? @/*

Remove boilerplate code from index.tsx and update meta tags:

import Head from 'next/head';

export default function Home() {
  return (
    <>
      <Head>
        <title>Job Board</title>
        <meta name='description' content='Job board app to connect job seekers to opportunities' />
        <meta name='viewport' content='width=device-width, initial-scale=1' />
        <link rel='icon' href='/favicon.ico' />
      </Head>
      <main>
            <h1>Find Your Dream Job</h1>
      </main>
    </>
  );
}

Start your local server using the command:

npm run dev

You should have your app running at http://localhost:3000

Installing the required dependencies

Run the following command in your terminal:

npm install @directus/sdk @chakra-ui/react @emotion/react @emotion/styled framer-motion react-icons

Directus SDK for fetching jobs
Chakra UI for styling (Emotion and Framer are Chakra UI dependencies)
React icons

Setting up Chakra UI

To use Chakra UI in your project, you need to set up the ChakraProvider at the root of your application.

Go to pages/_app.tsx and wrap the Component with the ChakraProvider.

// pages/_app.tsx
import type { AppProps } from 'next/app';
import { ChakraProvider } from '@chakra-ui/react'

export default function App({ Component, pageProps }: AppProps) {
  return (
    <ChakraProvider>
      <Component {...pageProps} />
    </ChakraProvider>
  );
}

Displaying the Job Listings

To display the job listings from Directus, we need to set up the types for our jobs and also create two components: the JobCard and JobList components.

Defining the Types for the Jobs

Since we’re working with TypeScript, to ensure type safety when working with job data from Directus, let’s set up an interface that defines the expected shape of each job object.

At the root of your project, create a new directory called lib, and inside it, a new file called directus.ts.

export type Job = {
  id: number;
  title: string;
  company: string;
  content: string;
  location: string;
  datePosted: string;
  logo: string;
  tags: string[];
  remote: boolean;
  salaryRange: string;
};

type Schema = {
  jobs: Job[];
};

Building the Job Card Component

Create a src/job-card.tsx file and input this code:

import { Avatar, Box, HStack, Heading, Icon, LinkBox, LinkOverlay, Stack, Tag, Text } from '@chakra-ui/react';
import NextLink from 'next/link';
import { MdBusiness, MdLocationPin, MdOutlineAttachMoney } from 'react-icons/md';
import { Job } from '@/lib/directus';
import { friendlyTime } from '@/lib/friendly-time';

type JobCardProps = {
  data: Job;
};

export function JobCard(props: JobCardProps) {
  const { data, ...rest } = props;
  const { id, title, company, location, datePosted, logo, tags, remote, salaryRange  } = data;

  return (
    <Box
      border='1px solid'
      borderColor='gray.300'
      borderRadius='md'
      _hover={{ borderColor: 'black', boxShadow: 'sm' }}
      p='6'
      {...rest}
    >
      <LinkBox as='article'>
        <Stack direction={{ base: 'column', lg: 'row' }} spacing='8'>
          <Avatar size='lg' name={title} src={logo} />
          <Box>
            <LinkOverlay as={NextLink} href={`/${id}`}>
              <Heading size='md'>{title}</Heading>
            </LinkOverlay>
            <Text>{company}</Text>
            <Stack mt='2' spacing={1}>
              <HStack spacing={1}>
                <Icon as={MdLocationPin} boxSize={4} />
                <Text>{location}</Text>
              </HStack>
              <HStack spacing={1}>
                <Icon as={MdBusiness} boxSize={4} />
                <Text>{remote === 'true' ? 'Remote' : 'Onsite'}</Text>
              </HStack>
              <HStack spacing={1}>
                <Icon as={MdOutlineAttachMoney} boxSize={4} />
                <Text>{salaryRange}</Text>
              </HStack>
            </Stack>
          </Box>
          <HStack spacing={2} flex='1'>
            {tags.map((tag, index) => (
              <Tag key={index} colorScheme='gray'>
                {tag}
              </Tag>
            ))}
          </HStack>
          <Text alignSelf={{ base: 'left', lg: 'center' }}>
            Posted {friendlyTime(new Date(datePosted))}
          </Text>
        </Stack>
      </LinkBox>
    </Box>
  );
}

Inside the lib directory and add a friendly-time.ts file to format the code:

export const friendlyTime = (date: Date) => {
  const seconds = Math.floor((new Date().getTime() - date.getTime()) / 1000);

  let interval = seconds / 31536000;

  if (interval > 1) {
    return Math.floor(interval) + ' years ago';
  }
  interval = seconds / 2592000;
  if (interval > 1) {
    return Math.floor(interval) + ' months ago';
  }
  interval = seconds / 86400;
  if (interval > 1) {
    return Math.floor(interval) + ' days ago';
  }
  interval = seconds / 3600;
  if (interval > 1) {
    return Math.floor(interval) + ' hours ago';
  }
  interval = seconds / 60;
  if (interval > 1) {
    return Math.floor(interval) + ' minutes ago';
  }
  return Math.floor(seconds) + ' seconds ago';
};

This component is styled and built using the Box,Stack, HStack, and more components from Chakra UI
The posted date is displayed using the friendlyTime code to format the datePosted into a user-friendly time format (e.g., "2 days ago")

Building the Job List Component

Inside the components directory, create a job-list.tsx file that shows the list of jobs

import { Stack } from '@chakra-ui/react';
import { JobCard } from './job-card';
import { Job } from '@/lib/directus';

type JobListProps = {
  data: Job[];
};

export function JobList(props: JobListProps) {
  const { data } = props;

  return (
    <Stack spacing='4'>
      {data.map((job, index) => (
        <JobCard key={index} data={job} />
      ))}
    </Stack>
  );
}

Fetching the Jobs from Directus

A crucial part of the job board is being able to fetch and display the latest job listings. To accomplish this, we’re going to use the Directus SDK.

At the root of your project, create a .env file and add your Directus URL

DIRECTUS_URL=add-your-directus-url-here

To share a single instance of the Directus SDK between multiple pages in this project, we need to set up a helper file that can be imported later.

Inside the directus.ts file, create a Directus client by importing the createDirectus hook and rest composable.

import { createDirectus, rest } from '@directus/sdk';

export interface Job {
  id: number;
  title: string;
  company: string;
  content: string;
  location: string;
  datePosted: string;
  logo: string;
  tags: string[];
  remote: boolean;
  salaryRange: string;
}

interface Schema {
  jobs: Job[];
}

const directus = createDirectus<Schema>(process.env.DIRECTUS_URL!).with(rest());

export default directus;

Now, go over to index.tsx and update the code to render the jobs

import { JobList } from '@/components/job-list';
import { Box, Heading, Stack } from '@chakra-ui/react';
import { readItems } from '@directus/sdk';
import Head from 'next/head';
import directus, { Job } from '../lib/directus';

export default function Home({ jobs }: { jobs: Job[] }) {
  return (
    <>
      <Head>
        <title>Job Board</title>
        <meta
          name='description'
          content='Job board app to connect job seekers to opportunities'
        />
        <meta name='viewport' content='width=device-width, initial-scale=1' />
        <link rel='icon' href='/favicon.ico' />
      </Head>
      <main>
        <Box p={{ base: '12', lg: '24' }}>
          <Stack mb='8' maxW='sm'>
            <Heading>Find Your Dream Job</Heading>
          </Stack>
          <JobList data={jobs} />
        </Box>
      </main>
    </>
  );
}

export async function getStaticProps() {
  try {
    const jobs = await directus.request(
      readItems('jobs', {
        limit: -1,
        fields: ['*'],
      })
    );

    if (!jobs) {
      return {
        notFound: true,
      };
    }

    // Format the image field to have the full URL
    jobs.forEach((job) => {
      job.logo = `${process.env.DIRECTUS_URL}assets/${job.logo}`;
    });

    return {
      props: {
        jobs,
      },
    };
  } catch (error) {
    console.error('Error fetching jobs:', error);
    return {
      notFound: true,
    };
  }
}

You should have something like this on your frontend

Displaying the Job Detail

With the ability to fetch job listings from Directus established, the next step is to dynamically display each job's content on individual job pages. Next.js provides a streamlined way to do this through its automatic static and server-side rendering features.

But first, we need to build out a JobContent Component.

Building the Job Content Component

Within the components folder, create a job-content.tsx file to show the job content for each job

import { Job } from '@/lib/directus';
import { Avatar, Box, Button, HStack, Heading } from '@chakra-ui/react';
import Link from 'next/link';

type JobContentProps = {
  data: Job;
};

export function JobContent(props: JobContentProps) {
  const { data } = props;
  const { content, logo, title, company } = data;

  return (
    <Box px={{ base: '12', lg: '24' }}>
      <Button as={Link} href='/'>
        Back to jobs
      </Button>
      <Box py='16'>
        <HStack spacing='4'>
          <Avatar size='lg' name={title} src={logo} />
          <Heading size='lg'>{company}</Heading>
        </HStack>
        <Box maxW='3xl' dangerouslySetInnerHTML={{ __html: content }} />
      </Box>
    </Box>
  );
}

To dynamically render the job pages, create a [jobId].tsx in the pages directory and put the following code in it:

import { readItem, readItems } from '@directus/sdk';
import { GetStaticPaths, GetStaticProps } from 'next';
import directus from '../lib/directus';
import { Box } from '@chakra-ui/react';
import { JobContent } from '@/components/job-content';
import { Job } from '../lib/directus';

type JobDetailsProps = {
  job: Job;
};

export default function JobDetails(props: JobDetailsProps) {
  const { job } = props;
  return (
    <Box p={{ base: '12', lg: '24' }}>
      <JobContent data={job} />
    </Box>
  );
}

export const getStaticPaths: GetStaticPaths = async () => {
  try {
    const jobs = await directus.request(
      readItems('jobs', {
        limit: -1,
        fields: ['id'],
      })
    );
    const paths = jobs.map((job) => {
      // Access the data property to get the array of jobs
      return {
        params: { jobId: job.id.toString() },
      };
    });
    return {
      paths: paths || [],
      fallback: false,
    };
  } catch (error) {
    console.error('Error fetching paths:', error);
    return {
      paths: [],
      fallback: false,
    };
  }
};

export const getStaticProps: GetStaticProps = async (context) => {
  try {
    const jobId = context.params?.jobId as string;

    const job = await directus.request(
      readItem('jobs', jobId, {
        fields: ['*'],
      })
    );

    if (job) {
      job.logo = `${process.env.DIRECTUS_URL}assets/${job.logo}`;
    }

    return {
      props: {
        job,
      },
    };
  } catch (error) {
    console.error('Error fetching job:', error);
    return {
      notFound: true,
    };
  }
};

The code fetches and renders dynamic job details using static site generation with Next.js.

Static Paths Generation (getStaticPaths):
- Implements the getStaticPaths function, a part of Next.js's static site generation.
- Requests job data using Directus's readItems function with limit: -1 to fetch all job IDs.
- Maps retrieved job IDs to an array of params objects to generate dynamic routes.
- Sets the paths array to the generated paths and fallback tofalse (no fallback behavior).
Static Props Generation (getStaticProps):
- Implements the getStaticProps function, used in static site generation to fetch data for a specific page.
- Extracts thejobId parameter from the context object to identify the requested job.
- Requests detailed job information using Directus's readItem function for the specified job.
- Modifies the job object by appending the logo URL with the DIRECTUS_URL.
- Returns fetched job data within the props object.

Now, whenever you click on a job, you’ll be able to see all the details about that job

Implementing the Search Functionality

To enable users to search for jobs by title in our application, we need to build out the functionality for querying the jobs data store based on the job title field. We also need to build out the search input UI to handle this.

In index.tsx update the code as follows:

export default function Home(props: { jobs: Job[] }) {
  const { jobs } = props;
  const router = useRouter();

  const searchQuery = router.query.search?.toString();
  const searchResult = searchQuery
    ? jobs.filter((job) => {
        return job.title.toLowerCase().includes(searchQuery.toLowerCase());
      })
    : jobs;

  return (
    <>
      <Head>
        <title>Job Board</title>
        <meta
          name='description'
          content='Job board app to connect job seekers to opportunities'
        />
        <meta name='viewport' content='width=device-width, initial-scale=1' />
        <link rel='icon' href='/favicon.ico' />
      </Head>
      <main>
        <Box p={{ base: '12', lg: '24' }}>
          <Stack mb='8' direction={{ base: 'column', md: 'row' }}>
            <Heading flex='1'>Find Your Dream Job</Heading>
            <InputGroup w='auto'>
              <InputLeftElement color='gray.400'>
                <FaSearch />
              </InputLeftElement>
              <Input
                placeholder='Search jobs...'
                onChange={(event) => {
                  const value = event.target.value;

                  router.replace({
                    query: { search: value },
                  });
                }}
              />
            </InputGroup>
          </Stack>
          <JobList data={searchResult} />
        </Box>
      </main>
    </>
  );
}

We use the useRouter hook from Next.js to access the query parameters from the URL.
If a search query was provided, we filter the jobs array to only include those whose title matched the search query in a case-insensitive manner. If no search query was present, we simply set the searchResult to the original jobs array without any filtering.

Here's the repository to find the code

Conclusion

In this tutorial, you've learned how to fetch job data from a Directus instance, display it on your app, and implement search functionality.

Some natural next steps could include:

Implementing user authentication via JWT tokens to allow job seekers to create custom profiles, save jobs, and track application status
Integrating email and notification systems to allow job alerts to be automatically sent to users when new jobs are posted
Adding advanced filtering and sorting of job results beyond just search title

If you have any questions or need further assistance, please feel free to drop by our Discord server.

Previewing Files With Google Docs Previews

Alex van der Valk — Thu, 24 Aug 2023 12:17:28 +0000

Using the file interface, you can store all types of files inside items in your Directus projects. However, there is no built-in way to preview files directly in the editor. I found an easy and reliable way to do this using Directus' Live Preview feature and Google Gview to preview many file formats without first having to download each file.

In your collection, create a File field. I recommend specifying a specific folder for the uploads here, because it can help keep your assets organized.
Ensure you have a static access token with a user who has permission to view your folder of files.
In your Collection configuration, scroll down to the Preview section.
In the Preview URL field add the following, replacing YOUR_DIRECTUS_URL with the URL for your Directus Project, and TOKEN with your static token.

    https://docs.google.com/gview?embedded=true&url=YOUR_DIRECTUS_URL/assets/?access_token=TOKEN

Using the variable tool in the Preview URL interface, add in the image ID just before the ? character in the URL.

Open up a record in your collection and select the Live Preview button in the top-right. Now you can preview the file inside Directus without having to download it first!

Building a Wedding Invite System with Node.js, Vonage, and Directus

Kevin Lewis — Mon, 14 Aug 2023 07:08:07 +0000

My wedding is coming up in just over a week, which is exciting. But you know what isn't exciting? Getting a confirmed guest list with all of the variations in invites and information gathered consistently. I'm going to show you how I built my wedding invite system with various types of invite (all-day/ceremony-only), auto-formatted contact information when RSVPs were submitted, and generated a constantly-updated guest-list.

Before You Start

You will need Node.js and a text editor installed on your computer.

You will also need a Directus project running - either using Directus Cloud or by Self Hosting - and an API token for your admin user.

Finally, sign up for a Vonage Developer account and take note of your API Key and Secret.

In your Directus project, create the following collections (and fields):

people - Primary Key Field: id (Generated UUID)
- first_name (Type: String, Interface: Input)
- last_name (Type: String, Interface: Input)
- rsvp (Type: Boolean, Interface: Toggle)
- requirements (Type: String, Interface: Input)
- is_plus_one (Type: Boolean, Interface: Toggle)
invites - Primary Key Field: slug (Manually entered string)
- message (Type: String, Interface: Input)
- people (Type: Alias, Interface: One to Many)
  - Related Collection: people
  - Foreign Key: invite
  - Display Template First Name Last Name
- plus_one_allowed (Type: Boolean, Interface: Toggle)
- ceremony_invite (Type: Boolean, Interface: Toggle)
- completed (Type: DateTime, Interface: Datetime)
- email (Type: String, Interface: Input)
- phone (Type: String, Interface: Input)

One invite will have multiple people, and optional characteristics (allowed +1, invited to ceremony). When guests respond, they will provide requirements (dietary/accessibility), and the person filling it in will provide an email and phone number. Finally, if given a +1 and it's used, a new person will be created and is_plus_one will be set to true.

Here's an illustration of an invite page, annotated to show where values in Directus will alter it.

The most minimal invite (one guest, reception-only, no +1) looks like this:

Create a new directory for this project and open it in a code editor. Create a .env file and populate it with your keys:

DIRECTUS_URL=your_project_url_here
DIRECTUS_TOKEN=your_admin_token_here

Run npx gitignore node to create a suitable .gitignore file for this project. Create a package.json file with npm init -y and then install our dependencies:

npm install dotenv express hbs @directus/sdk

If you don't want to follow along, you can now skip to the bottom of this tutorial for the complete code.

Create an index.js file and open it in your code editor.

Set Up Application

Create and set up an Express.js application with the handlebars view engine:

import 'dotenv/config';
import express from 'express';
import { engine } from 'express-handlebars';

const app = express();
app.use(express.static('public'));
app.use(express.urlencoded({ extended: true }));

app.engine('handlebars', engine());
app.set('view engine', 'handlebars');
app.set('views', './views');

app.get('/invite/:slug', (req, res) => {
  res.render('invite', { 
    layout: false, 
    name: req.params.slug 
  });
});

app.listen(3000);

Create a views directory and, inside of it, an invite.handlebars file:

<!DOCTYPE html>
<html>
<body>
   {{ name }}
</body>
</html>

Run your application with node index.js in the terminal, and navigate to localhost:3000/invite/hello. You should see a page with 'hello'.

Set Up Directus SDK

Import and initialize a new Directus client with rest features. Import the createItem, readItem, and updateItem functions for later.

import 'dotenv/config';
import express from 'express';
import { engine } from 'express-handlebars';

import { createDirectus, staticToken, rest, createItem, readItem, updateItem } from '@directus/sdk'; // [!code ++]
const directus = createDirectus(process.env.DIRECTUS_URL) // [!code ++]
  .with(rest()) // [!code ++]
  .with(staticToken(process.env.DIRECTUS_TOKEN)); // [!code ++]

Create Invite Pages

Update the invite route handler to utilize the Directus SDK and read the invite from your Directus project.

app.get('/invite/:slug', async (req, res) => {
  const data = await directus.request( // [!code ++]
    readItem('invites', req.params.slug, { // [!code ++]
      fields: ['*', { people: [ 'id', 'first_name', 'last_name' ] }] // [!code ++]
    }) // [!code ++]
  ); // [!code ++]

  res.render('invite', { 
    layout: false, 
    name: req.params.slug // [!code --]
    ...data // [!code ++]
  }); 
});

Update the content of the <body> tag to include values from the invite:

<body>
  <h1>You're invited!</h1>
  <p>{{ message }}</p>
  <div>
    {{#if ceremony_invite}}
      <p>Ceremony-specific information</p>
    {{/if}}
    <p>Reception-specific information</p>
  </div>
</body>

Show everyone the personalized message as part of their invite and the reception details. Only a subset of guests are invited to the ceremony as denoted by cermeony_invite being set to true.

Create five items in the people collection with just a name, and four invites to test:

ceremony_invite = false, plus_one_allowed = false, slug = 'a'
ceremony_invite = true, plus_one_allowed = false, slug = 'b'
ceremony_invite = false, plus_one_allowed = true, slug = 'c'
ceremony_invite = true, plus_one_allowed = true, slug = 'd' (assign two people to this invite)

This should give all key permutations to test against. Restart your server, navigate to localhost:3000/invite/a and you should see only the reception information. When you go to localhost:3000/invite/b you should see ceremony information as well.

Build RSVP Form

Underneath the existing <div>, add a conditional that will only show the form is the invite has not yet been RSVP'd to:

{{#if completed}}
  <p>Thanks for responding</p>
{{else}}
  <!-- Further code goes here -->
{{/if}}

In the {{else}} block, create a form:

<form action="/rsvp" method="POST">

  {{#each people}}
    <div style="border: 1px solid black;">
      <h2>{{ this.first_name }} {{ this.last_name }}</h2>

      <input type="radio" name="rsvp-{{ this.id }}" value="false" id="rsvp-no-{{ this.id }}" required>
      <label for="rsvp-no-{{ this.id }}">Accept</label><br>

      <input type="radio" name="rsvp-{{ this.id }}" value="true" id="rsvp-yes-{{ this.id }}" required>
      <label for="rsvp-yes-{{ this.id }}">Regrets</label><br>

      <input type="text" name="requirements-{{ this.id }}" id="requirements-{{ this.id }}" placeholder="Requirements">
    </div><br>
  {{/each}}

  <p>Only one needed per invite</p>
  <input type="email" placeholder="Email" name="email" required>
  <input type="text" placeholder="Phone" name="phone" required>
  <input type="hidden" value="{{ slug }}" name="slug">
  <input type="submit">
</form>

Let's break this down:

The form will submit a POST request to /rsvp. This will be created later.
For every person assigned to this invite, create a set of three inputs - a pair of radio buttons for RSVP yes/no, and one to optionally collect any accessibility or dietary requirements. Note that all inputs have a dynamic name which includes that person's ID from the database. For example, name="rsvp-{{ this.id }}" would become name="rsvp-ff028423-7111…"
There is one email and phone number collected per RSVP.
A hidden field contains the slug, so it is also submitted with the rest of the form.

Add +1 Form Fields

If the invite has plus_one_allowed set to true, show additional fields to collect their information:

{{/each}}

{{#if plus_one_given}} // [!code ++]
  <div style="border: 1px solid black;"> // [!code ++]
    <h2>Your +1</h2> // [!code ++]
    <input type="text" name="first-name-plus-one" id="first-name-plus-one" placeholder="First Name"> // [!code ++]
    <input type="text" name="last-name-plus-one" id="last-name-plus-one" placeholder="Last Name"> // [!code ++]
    <input type="text" name="requirements-plus-one" id="requirements-plus-one" placeholder="Requirements"> // [!code ++]
  </div> // [!code ++]
{{/if}} // [!code ++]

<p>Only one needed per invite</p>

Restart your server, navigate to localhost:3000/invite/b and you should not see the +1 fields. When you go to localhost:3000/invite/d you should. Here's what the form looks like when a +1 is allowed on the invite:

It isn't winning any design awards, but it works.

Submit RSVP

Create a new route handler in index.js for the POST submission:

app.post('/rsvp', async (req, res) => {
  console.log(req.body);
});

Restart the server, fill and submit the form. The terminal should look something like this:

Update People With Their RSVP

To get a list of only people IDs, filter this object to an array of just the properties starting with rsvp, and then remove rsvp- from the start of the strings. Under the console.log:

const rsvps = Object.keys(req.body)
  .filter(k => k.includes('rsvp'))
  .map(k => k.split('rsvp-')[1]);

Then, loop through these IDs and update each person with their RSVP and requirements:

for(let rsvp of rsvps) {
  await directus.request(
    updateItem('people', rsvp, { 
      rsvp: req.body[`rsvp-${rsvp}`],
      requirements: req.body[`requirements-${rsvp}`]
    })
  );
}

Create Person Item For +1

If the +1 form was filled in, create a new person and add their ID to the RSVPs list. Under the for loop add the following:

if(req.body['first-name-plus-one']) {
  const { id } = await directus.request(
  createItem('people', {
    first_name: req.body['first-name-plus-one'],
    last_name: req.body['last-name-plus-one'],
    requirements: req.body['requirements-plus-one'],
    is_plus_one: true,
    rsvp: true
   })
  );
  rsvps.push(id)
}

Update Invite

Each invite contains a phone number and email address of the lead contact. Under the for loop, update the invite:

await directus.request(
  updateItem('invites', req.body.slug, { 
    email: req.body.email,
    phone: req.body.phone,
    people: rsvps,
    completed: new Date()
  })
);

If there was a +1, the new person will be added to the invite. The value of completed will also be set to the current Datetime. In Directus, you'll easily be able to see when an RSVP was made. In the application, this will replace the form with the message "Thanks for responding".

As the form will not appear when completed has a value, redirect back to the same page and it will appear as if the form has been replaced with the thank you message:

res.redirect(`/invite/${req.body.slug}`);

Standardize Phone Numbers

I can tell you from past experience - no one ever fills in their phone number consistently, and I wanted to build a batch update system so we could send people important messages as the day approaches.

To format numbers, I used the Vonage Number Insight API. In your Directus Project Settings create a new Flow.

Use an non-blocking Event Hook Trigger so the item is added to the collection and then the flow is run. Keep the scope to only the items.update on the Invites collection.

Add a new Request URL operation and set the URL to https://api.nexmo.com/ni/basic/json?api_key=VONAGE_API_KEY&api_secret=VONAGE_API_SECRET&number={{$trigger.payload.phone}}, being sure to change the values for your key and secret.

Once the request has been successful, add an Update Data operation on the Invites collection. Set the payload to the following:

{
    "phone": "{{$last.data.international_format_number}}"
}

Save the Flow and test it by submitting a new invite RSVP. You may need to manually set an invite's Completed value to null to see the form again. The whole flow should look like this:

See Guest List

To see a running guest-list, navigate to the People collection in the content module and add a filter RSVP = true. You can see just the ceremony list by adding the filter Invite -> Ceremony Invite = true.

Summary & Next Steps

In this tutorial, you have created a wedding invite and RSVP system backed by a Directus database, and then standardized provided data using the Vonage Number Insight API.

Now that you have standardized data, you may choose to send batch messages via SMS or email using Flows.

If you have any questions or feedback, feel free to join our Discord server.

Complete Code

index.js

import 'dotenv/config';
import express from 'express';
import { engine } from 'express-handlebars';
import { createDirectus, staticToken, rest, createItem, readItem, updateItem } from '@directus/sdk';
const directus = createDirectus(process.env.DIRECTUS_URL)
  .with(rest())
  .with(staticToken(process.env.DIRECTUS_TOKEN));

const app = express();
app.use(express.static('public'));
app.use(express.urlencoded({ extended: true }));

app.engine('handlebars', engine());
app.set('view engine', 'handlebars');
app.set('views', './views');

app.get('/invite/:slug', async (req, res) => {
  const data = await directus.request(
    readItem('invites', req.params.slug, { 
      fields: ['*', { people: [ 'id', 'first_name', 'last_name' ] }] 
    })
  );
  res.render('invite', { layout: false, ...data });
});

app.post('/rsvp', async (req, res) => {
  console.log(req.body)
  // Get list of RSVP IDs
  const rsvps = Object.keys(req.body)
    .filter(k => k.includes('rsvp'))
    .map(k => k.split('rsvp-')[1]);

  // Update people with RSVPs
  for(let rsvp of rsvps) {
    await directus.request(
      updateItem('people', rsvp, { 
        rsvp: req.body[`rsvp-${rsvp}`],
        requirements: req.body[`requirements-${rsvp}`]
      })
    );
  }

  // Add +1 if exists
  if(req.body['first-name-plus-one']) {
    const { id } = await directus.request(
      createItem('people', {
        first_name: req.body['first-name-plus-one'],
        last_name: req.body['last-name-plus-one'],
        requirements: req.body['requirements-plus-one'],
        is_plus_one: true,
        rsvp: true
      })
    );
    rsvps.push(id);
  }

  // Update invite
  await directus.request(
    updateItem('invites', req.body.slug, { 
      email: req.body.email,
      phone: req.body.phone,
      people: rsvps,
      completed: new Date()
    })
  );

  res.redirect(`/invite/${req.body.slug}`);
});

app.listen(3000);

views/invite.handlebars

<!DOCTYPE html>
<html>
<body>
  <h1>You're invited!</h1>
  <p>{{ message }}</p>
  <div>
    {{#if ceremony_invite}}
      <p>Ceremony-specific information</p>
    {{/if}}
    <p>Reception-specific information</p>
  </div>
  {{#if completed}}
    <p>Thanks for responding</p>
  {{else}}
    <form action="/rsvp" method="POST">
      {{#each people}}
        <div style="border: 1px solid black;">
          <h2>{{ this.first_name }} {{ this.last_name }}</h2>

          <input type="radio" name="rsvp-{{ this.id }}" value="false" id="rsvp-no-{{ this.id }}" required>
          <label for="rsvp-no-{{ this.id }}">Accept</label><br>

          <input type="radio" name="rsvp-{{ this.id }}" value="true" id="rsvp-yes-{{ this.id }}" required>
          <label for="rsvp-yes-{{ this.id }}">Regrets</label><br>

          <input type="text" name="requirements-{{ this.id }}" id="requirements-{{ this.id }}" placeholder="Requirements">
        </div>
        <br>
      {{/each}}
      {{#if plus_one_allowed}}
      <div style="border: 1px solid black;">
        <h2>Your +1</h2>
        <input type="text" name="first-name-plus-one" id="first-name-plus-one" placeholder="First Name">
        <input type="text" name="last-name-plus-one" id="last-name-plus-one" placeholder="Last Name">
        <input type="text" name="requirements-plus-one" id="requirements-plus-one" placeholder="Requirements">
      </div>
      {{/if}}
      <p>Only one needed per invite</p>
      <input type="email" placeholder="Email" name="email" required>
      <input type="text" placeholder="Phone" name="phone" required>
      <input type="hidden" value="{{ slug }}" name="slug">
      <input type="submit">
    </form>
  {{/if}}
</body>
</html>

}

Building a Form and Email Notification System with Directus and Next.js

Esther Adebayo — Wed, 09 Aug 2023 15:13:00 +0000

Well-designed data collection and notification processes empower businesses to gather key information about their customers in an efficient and actionable manner.

In this tutorial, we will walk through how to use Directus as a composable data platform that stores form data and sends instant email notifications.

Here’s a quick overview of the system:

Users complete a form in a Next.js app
Directus stores the submitted information in a collection
When a new submission is stored, an automated workflow is triggered in Directus to send an email notification to the business and a thank you email to the user

Prerequisites

To follow along with this tutorial, it is important to have the following:

A Directus project, either self-hosted or a Cloud account.
Basic knowledge of React.js and Next.js.

Setting up a Directus Collection for Data Storage

To begin, log in to your Directus app and navigate to Settings > Data Model

Click the + icon to create a new collection called “user_data”.

Add the following fields to the "user_data" collection and save:

full_name (Type: String, Interface: Input): To capture the user's full name.
email_address (Type: String, Interface: Input): To store the user's email address.
phone_number (Type: String, Interface: Input): To store the user's phone number.
country (Type: String, Interface: Input): Implement a field to record the user's country.
about_you (Type: Text, Interface: Textarea): To collect additional information from users, such as their interests or feedback.

Enabling Public Access for the Collection

To enable open access to the data stored within this collection, we need to give it public access.
Head over to Settings > Roles & Permission

Navigate to the public role and then toggle Create permission from “No Access” to “All Access”.

This setting ensures that the data stored in the collection is easily accessed without authentication.

Now that the collection is in place, it's time to proceed with building the frontend of our application using Next.js.

Creating the Next.js Application

Install Next.js by running this command:

npx create-next-app@latest form-email-app

Once the installation is complete, proceed to the newly created directory:

cd form-email-app

Proceed to install dependencies and run the scaffolded Next.js application with the command:

npm run dev

Now, open http://localhost:3000/ on your browser, and you should see the Next.js starter page

This project uses the Next.js App directory.

Back in the code editor, enable Server Actions in Next.js, by updating the next.config file.

const nextConfig = {
  experimental: {
    serverActions: true,
  },
};

Building the form component to capture user data

Go over to the page.js file. We’ll do some cleanup here.

First, remove the placeholder code and create a form component with the following fields:

Full Name
Email Address
Phone Number
Country
About You

Your code should look like this:

export default function Home() {
  // handleSubmit function to be here

return (
    <main>
      <form action={handleSubmit}>
        <h1>User Data Form</h1>
        <p>Please fill in your details below</p>
        <div className='form-flex'>
          <label htmlFor='name'>Full Name</label>
          <input id='name' name='full_name' required />
        </div>
        <div className='form-flex'>
          <label htmlFor='email'>Email Address</label>
          <input type='email' name='email_address' id='email' required />
        </div>
        <div className='form-flex'>
          <label htmlFor='phone'>Phone Number</label>
          <input type='tel' name='phone_number' id='phone' required />
        </div>
        <div className='form-flex'>
          <label htmlFor='country'>Choose your Country</label>
          <select name='country' id='country' required>
            <option value='kenya'>Kenya</option>
            <option value='usa'>United States</option>
            <option value='germany'>Germany</option>
            <option value='uae'>United Arab Emirates</option>
          </select>
        </div>
        <div className='form-flex'>
          <label htmlFor='aboutyou'>About You</label>
          <textarea
            id='aboutyou'
            name='about_you'
            rows='4'
            cols='50'
            required
            placeholder='Enter information about yourself...'
          />
        </div>
        <button type='submit'>Submit</button>
      </form>
    </main>
  );
}

Integrating the Directus SDK with Next.js

Install the SDK using the command:

npm install @directus/sdk

Import the required composables at the top of your file:

import { createDirectus, rest, createItem } from "@directus/sdk"

Now, create a composable client with REST support

const client = createDirectus('<http://directus.example.com>').with(rest());

💡 Remember to change the http://directus.example.com URL to your actual URL.

Now, we need to set up the handleSubmit function that sends data using the Directus SDK

 const handleSubmit = async (formData) => {
    'use server';

    const full_name = formData.get('full_name');
    const email_address = formData.get('email_address');
    const phone_number = formData.get('phone_number');
    const country = formData.get('country');
    const about_you = formData.get('about_you');

    try {
      await client.request(
        createItem('user_data', {
          full_name,
          email_address,
          phone_number,
          country,
          about_you,
        })
      );
    } catch (error) {
      console.log(error);
    }
  };

Whenever a user completes the form, the data is sent to the collection.

Configuring the Email Notification Flow

Directus Flows enable you to create automation to streamline various processes within your Directus project.

To set up a flow, go to Settings > Flows

Click the + icon to create a new flow called “Data Email Flow” and add a description.

Next, we need to set up a trigger for our flow. Triggers are events that initiate a workflow.

For this flow, choose the following options:

Trigger: Select the event hook as the trigger.
Action: The action we'll take is non-blocking, meaning it won't cause delays in the process.
Scope: The scope of this flow is focused on items.create.
Collection: We'll be working with the user_data collection.

Adding Operations to the Flow

Operations are specific tasks to be carried out in response to the trigger event in a flow.

Add the first operation, which is to send an email notification to you as the administrator.

Edit the flow to create an operation called "Email Notification to Me"

Now, select Send Email and fill in the email address the notification is to be sent to and the subject of the email.

Keep the type of the body as Markdown but feel free to explore other types.

Since you have the email of the user, you can customize the email body with the name of the user with {{$trigger.payload.full_name}}.

Now, save the flow.

Whenever your form is completed, you'll get an email notification.

That's not all! Additionally, you need to send follow-up emails to users as a gesture of appreciation for completing the form and even offer an incentive.

To achieve this, include an additional operation in our flow similar to the one above.

Setting up the operation to send emails to users

Head over to your flow and edit it.

Include an additional operation for sending an email following the previously mentioned steps.
However, this time, make the receiver email dynamic, adapting its value to the information filled out by the user using {{$trigger.payload.email_address}}.

Complete the rest of the fields and save your flow.

Toggle open to see a sample email body

 Hi {{$trigger.payload.full_name}},

 Your feedback has been received and much appreciated.

 Use this coupon code on your next checkout: "PRO11".

 Till next time,

 Thanks.

Now go ahead and test your entire application by completing the user data form. You'll get an instant notification in your email. The user will also receive the thank you email.

Conclusion

You’ve just learnt how to set up the data collection process and implement an email notification system using Directus.

Further enhance and customize this application to suit your project needs by:

Implementing Real-Time Updates: Add real-time to get the most up-to-date data instantly.
Enabling User Permissions and Roles: This helps to control data access and security
Utilizing Insights: Directus Insights allow you to visualize data and gain more knowledge from your collected data.

If you have any questions or need further assistance, please feel free to drop by our Discord server.

Announcing the Directus AI Hackathon

Kevin Lewis — Wed, 09 Aug 2023 14:40:55 +0000

We're excited to announce our very first Directus Hackathon - this time with the theme of AI. Directus provides an extensive toolkit to work with data and is perfect for huge enterprise and hobby projects alike. We’re challenging you to bring your creativity and technical skills to the table for the chance to win cash prizes and swag.

Key Information

Start: August 3 2023 at 00:00 UTC.
End: August 31 2023 at 23:59 UTC.
One challenge: Build a project that utilizes AI and Directus.
Two prizes: $1000 USD and a $250 USD charity donation from our list of charities. One decided by the Directus Core Team, one by community voting.

The Theme

We want to see how you would combine Directus and AI features by creating new Directus extensions.

You may choose to build a new Insights Panel for our dashboards, a custom Flows Operation for our automations feature, a cool Editor Interface to support content creation or review, or any of the other extensions types.

We’re pretty open to seeing what you build, so we’ve left the scope quite wide for this one.

Submitting Your Project

To submit your project, you must:

Add your extension code to a public repository on GitHub.
Use our README template and replace anything in curly brackets with your submission's value.
Add the directus and directus-ai-hackathon tags to your GitHub repository.
Fill in this form to provide your email address so we can get in touch with results.

We encourage all projects to include a LICENSE file in your repository with the Apache License 2.0, the GNU General Public License v3.0, or the MIT License.

The submission period ends on August 31 2023 at 23:59 UTC. You must complete all of the steps above by this time to be eligible. If you work with others, only one person must complete the steps.

Judging

On September 1 2023, we will curate all valid submissions into a blog post on the Directus Developer Blog with links to the last commit before the submission deadline (further commits will not be assessed).

When judging projects, we will look at the following criteria with no specific weighting:

Creative: Is the idea original and innovative?
Technical: How effectively do you integrate AI? Is the project well-executed? Does it run?
Relevance: Do you solve a real problem faced by people?
Presentation: Have you taken time to add polish to your project?

Judging will take place from September 1 2023 until September 10 at 23:59 UTC.

Community Vote

The Prizes

Both the Directus Core Team and Community Vote prizes are the same:

$1000 USD awarded to the project submitter.
$250 USD donation to a charity of the winner’s choice from the following list:
- codebar - a charity that facilitates the growth of a diverse tech community by running free regular programming workshops for minority groups in tech.
- VetsInTech - who support transitioning military, veterans and spouses of either with reintegration services, and by connecting them to the national technology ecosystem.
- Out In Tech - the world’s largest non-profit community of LGBTQ+ tech leaders.
- Carbon180 works toward developing equitable, science-based policies that will scale carbon removal.
- Cool Earth works with rainforest communities, tackles the root causes of deforestation, and protects vital carbon sinks.

Winners will be announced at a live Discord event on September 11 2023, and winners contacted over email on the same day.

Get Started

You can get started using a hosted Directus Cloud project or by running your own locally, using Docker, in just a few minutes

You can find educational resources here on the Directus Developer Blog, in our docs guides, and on our YouTube channel.

At any point during the hacking period, feel free to drop by our Discord server and ask for help in the #help-general channel, or ask questions about the hackathon in the #hackathon channel. We also have weekly Office Hours events on Thursdays which we’ll dedicate to the hackathon throughout August.

Additional Notes

Multiple submissions are allowed, and will be judged separately.
You own your projects - our incentive is to see the cool things people build.
We don’t handle prize-splitting, so if you’re working with others and win, we’ll send the prize to the Team Lead and they’ll be responsible for distributing it.
You can find the Terms & Conditions for this contest here.

Let’s Go!

This is the first time we’re running our own hackathon, and we’re always open to adapting the format for future editions. Please do provide feedback and what does and doesn’t work for you.

We are so excited to see your projects and the cool ideas you come up with!