Forem: Marvin Bangemann

Fetch & Build your Navigation

Marvin Bangemann — Thu, 22 Feb 2024 15:00:00 +0000

Previous Posts:

Crafting an Effective Navigation for Your Astro Website

Welcome to a pivotal installment in our series where we dive into creating a dynamic navigation for your Astro-based website. The inspiration for this series was sparked by community interest on a Reddit post, encouraging me to share my experiences and tackle the imposter syndrome head-on. Let's explore the rationale behind this approach: it empowers your marketing team (or whoever manages the website's backend) to adjust navigation items, including order, addition, and removal of subitems, directly within WordPress. This functionality is a game-changer for those seeking flexibility and ease of management.

Configuring Your WordPress Backend for Navigation Management

Following up on a promise from my previous post, we'll delve deeper into registering a new endpoint for navigation items. This is achieved by adding the following snippet to your get_menu.php file:

add_action('rest_api_init', function () {
    register_rest_route('wp/v2', '/menu/(?P<menu_name>[\w-]+)', array(
        'methods' => 'GET',
        'callback' => 'wp_rest_get_menu',
        'permission_callback' => '__return_true',
        'args' => array(
            'menu_name' => array(
                'validate_callback' => function ($param, $request, $key) {
                    // Additional validation logic if needed
                    return is_string($param) && strlen($param) <= 20; // Example: Ensure it's a string and not longer than 20 characters
                },
                'sanitize_callback' => 'sanitize_text_field',
            ),
        ),
    ));
});

This code snippet effectively makes your menus accessible via the REST API, adhering to the WordPress REST API schema. You can fetch menu items by visiting https://your-wordpress-url.com/wp-json/wp/v2/menu/menu-endpoint, with "menu-endpoint" being the identifier you set in your menus configuration.

To streamline menu management on the Astro frontend, we introduce an enumeration for different menus:

const GetNavigationParamsSchema = z.object({
  endpoint: z.enum(['main-navigation', 'sub-navigation', 'footer-navigation', 'footer-sub-navigation']),
});

export type GetNavigationParams = z.infer<typeof GetNavigationParamsSchema>;

Typing Your Menus in Astro with Zod

Ensuring type safety and data integrity is crucial, hence why we define our request and response types using Zod. This aids in processing the expected data without errors. Here's how to structure your navigation item data schema:

// Base schema for navigation item data, without the children property
const baseNavigationItemDataSchema = z.object({
  ID: z.number(),
  post_author: z.string().optional(),
  post_date: z.string().optional(),
  post_date_gmt: z.string().optional(),
  post_content: z.string().optional(),
  post_title: z.string().optional(),
  post_excerpt: z.string().optional(),
  post_status: z.string().optional(),
  comment_status: z.string().optional(),
  ping_status: z.string().optional(),
  post_password: z.string().optional(),
  post_name: z.string().optional(),
  to_ping: z.string().optional(),
  pinged: z.string().optional(),
  post_modified: z.string().optional(),
  post_modified_gmt: z.string().optional(),
  post_content_filtered: z.string().optional(),
  post_parent: z.number().optional(),
  guid: z.string().optional(),
  menu_order: z.number().optional(),
  post_type: z.string().optional(),
  post_mime_type: z.string().optional(),
  comment_count: z.string().optional(),
  filter: z.string().optional(),
  db_id: z.number().optional(),
  menu_item_parent: z.string().optional(),
  object_id: z.string().optional(),
  object: z.string().optional(),
  type: z.string().optional(),
  type_label: z.string().optional(),
  url: z.string().optional(),
  title: z.string().optional(),
  target: z.string().optional(),
  attr_title: z.string().optional(),
  description: z.string().optional(),
  classes: z.array(z.string()).optional(),
  xfn: z.string().optional(),
});

This is the Reponse we get from our wordpress backend when we call the menu api. It's a lot of different stuff, we don't really need for our frontend. So we can use zod to define the data we want to use, to guarantee type-safety inside our Components later.

export const baseNavigationItemSchema = z.object({
  title: z.string(),
  url: z.string(),
  ID: z.number(),
  menu_order: z.number(),
  menu_item_parent: z.string(),
  type: z.string(),
  object: z.string(),
  post_status: z.string(),
});

Looks cleaner, right? But we aren't done yet. To accommodate navigation hierarchies, we extend our base schema to include child items, leveraging Zod's capabilities for recursive types: Here's how I did it, according to Zods documentation:

const navigationItemSchema = baseNavigationItemSchema.extend({
  children: z.array(z.lazy(() => baseNavigationItemSchema)).optional(),
});

Now we can define a schema for our navigation and export it together with our navigationItem as types.

export const navigationSchema = z.object({
  id: z.number(),
  title: z.string(),
  items: z.array(navigationItemSchema),
});

export type NavigationItem = z.infer<typeof navigationItemSchema>;
export type Navigation = z.infer<typeof navigationSchema>;

Processing and Fetching Navigation Data

Before utilizing the navigation data in our Astro components, we must process it to correctly assign child items to their parents. This ensures our navigation structure mirrors the setup in WordPress. Here's an outline of the processing function:


export function processNavigationItems(items: NavigationItem[]): NavigationItem[] {
  // The final processed array with top-level navigation items
  const processedItems: NavigationItem[] = [];

  items.forEach(item => {
    const currentItem = itemsMap.get(item.ID);
    if (!currentItem) {
      return; // Skip if the current item is undefined
    }

    if (item.menu_item_parent && item.menu_item_parent !== '0') {
      // If the item has a parent, add it to the parent's 'children' array
      const parentItem = itemsMap.get(parseInt(item.menu_item_parent));
      if (parentItem) {
        if (!parentItem.children) {
          parentItem.children = []; // Initialize 'children' property as an empty array if it is undefined
        }
        parentItem.children.push(currentItem);
      }
    } else {
      // If the item has no parent, it's a top-level item
      processedItems.push(currentItem);
    }
  });

  return processedItems;
}

Following processing, we fetch the navigation data, ensuring it's ready for component integration:

function getNavigationHandler(client: AxiosInstance) {
  return async (params: GetNavigationParams): Promise<NavigationItem[]> => {
    try {
      const navigationData = await client.get<NavigationItem[]>(`menu/${params.endpoint}`);
      return navigationData.data; // Return the 'data' property of the navigationData object
    } catch (error) {
      console.error(error);
      throw error;
    }
  };
}

export async function fetchNavigation({ endpoint }: GetNavigationParams): Promise<NavigationItem[]> {
  try {
    // Create an instance of your navigation handler
    const navigationHandler = getNavigationHandler(fetchApi);
    const navigationParams: GetNavigationParams = { endpoint };
    const rawItems = await navigationHandler(navigationParams);

    // Process the raw navigation items
    return processNavigationItems(rawItems);
  } catch (error) {
    console.error('Error fetching navigation:', error);
    return [];
  }
}

As you may have noticed, there is a getNavigationHandler. This is how we communicate with our prior defined Interceptor, when we set up Astros API Layer.

Building Your Navigation Component in Astro

With our processed navigation data, we can now construct the navigation in our Astro frontend. The component structure involves iterating over navigation items and dynamically generating links, including handling sub-menus:

// Navigation.astro
---
import NavigationLink from "./NavigationLink.astro";
import type { NavigationItem } from "@lib/api/fetchNavigation";

type Props = {
  navigationItems: NavigationItem[];
};

const { navigationItems } = Astro.props;

---

<nav>
  <ul>
    {navigationItems.map((item) => (
      <li>
        <NavigationLink item={item} />
        {item.children && item.children.length > 0 && (
          <ul class="sub-menu">
            {item.children.map((subItem: NavigationItem) => (
              <li>
                <NavigationLink item={subItem}/>
              </li>
            ))}
          </ul>
        )}
      </li>
    ))}
  </ul>
</nav>

A complementary component, NavigationLink, is used to reduce code repetition and enhance readability:

---
const { item, className } = Astro.props;
---

<a
  href={item.url}
  aria-label={`Link to ${item.title}`}
  title={item.title}
  data-navigation-key={item.ID}
  data-astro-prefetch="hover"
  class={className}>
  {item.title}
</a>

This approach ensures that your Astro frontend benefits from a dynamic, easily manageable navigation system powered by WordPress. I hope this guide proves useful and inspires further exploration of headless CMS integrations.

Stay tuned for the next topic, where we'll explore handling Gutenberg Blocks in Astro.

Your feedback and questions are always welcome!

API Configuration & Data Fetching

Marvin Bangemann — Wed, 21 Feb 2024 14:54:00 +0000

Following my initial discussion, this chapter delves into employing WordPress as a headless CMS for Astro, focusing on Advanced Custom Fields for content structuring. Initially straightforward, the challenge lies in bridging WordPress with Astro.

My development environment, a mirrored structure of WordPress themes synced via rsync across staging and production, emphasizes developer-centric workflow. By localizing changes to the theme folder, it enhances developer experience and simplifies WordPress use for non-developers. Fields managed through PHP in the theme folder ensure version control and clarity.

Essential Theme Files Overview

Organized as follows, the theme structure facilitates efficient management:

wp-content/themes/wp-rest
├── api/
│   ├── endpoints/
│   │   └── get_menu.php
│   └── endpoint-registration.php
├── blocks/
│   ├── textbox/
│   │   ├── acf.php
│   │   ├── block.json
│   │   └── preview.php
│   └── block-registration.php
├── config/
│   ├── block-access.php
│   ├── menus.php
│   └── setup.php
└── functions.php

`functions.php` Core Functionality

Central to theme operation, this file orchestrates the loading of various scripts.

// Include configuration files
require get_template_directory() . '/config/setup.php';
require get_template_directory() . '/config/block-access.php';
require get_template_directory() . '/config/menus.php';

// Include API endpoints and block methods
require get_template_directory() . '/api/endpoint-registration.php';
require get_template_directory() . '/blocks/block-registration.php';

Theme Setup in `setup.php`

Adjusts WordPress features to match project needs.

function wp_rest_setup() {
    remove_theme_support('core-block-patterns');
    add_theme_support('align-wide');
}
add_action('after_setup_theme', 'wp_rest_setup');

Block Access Management in `block-access.php`

Specifies block access based on user roles, enhancing content customization.

function wp_rest_define_block_groups() {
    $common_blocks = ['core/image', 'core/group', 'core/columns', 'acf/textbox'];
    $editor_blocks = array_merge($common_blocks, ['core/gallery']);
    $admin_blocks = array_merge($editor_blocks, ['core/code', 'core/html']);

    return ['administrator' => $admin_blocks, 'editor' => $editor_blocks, 'default' => $common_blocks];
}

function wp_rest_assign_block_groups($allowed_blocks, $post) {
    $block_groups = wp_rest_define_block_groups();
    $current_user = wp_get_current_user();

    return $block_groups[in_array('administrator', $current_user->roles) ? 'administrator' : (in_array('editor', $current_user->roles) ? 'editor' : 'default')];
}
add_filter('allowed_block_types_all', 'wp_rest_assign_block_groups', 10, 2);

Menu Configuration in `menus.php`

Registers menus within the theme for controlled navigation management.

function wp_rest_register_menus() {
    register_nav_menus([
        'overlay_menu' => esc_html__('Main Navigation', 'wp-rest'),
        'header_submenu' => esc_html__('Sub Navigation', 'wp-rest'),
        'footer_menu' => esc_html__('Footer Navigation', 'wp-rest'),
        'footer_submenu' => esc_html__('Footer Sub Navigation', 'wp-rest'),
    ]);
}
add_action('after_setup_theme', 'wp_rest_register_menus');

Block Registration Process in `block-registration.php`

Handles custom block registration, ensuring seamless integration.

require __DIR__ . '/textbox/acf.php';
require __DIR__ . '/textbox/preview.php';

function wp_rest_register_acf_blocks() {
    register_block_type(__DIR__ . '/textbox', [
        'render_callback' => 'textbox_block_render_callback',
    ]);
}
add_action('init', 'wp_rest_register_acf_blocks');

Advanced Custom Fields Setup in `acf.php`

Defines field groups programmatically for API visibility.
Dig into the ACF Documentation, or just export your ACF Field Groups via it's GUI to PHP and have a look at the generated code.
Alternatively you can stick with the GUI

Preview Functionality in `preview.php`

Offers a backend glimpse of custom blocks, aiding in layout decisions. Here's an example of a preview for a simple text box block:

Custom API Endpoint Creation in `endpoint-registration.php`

Explored further in Chapter 3, this script introduces tailored REST API endpoints.

Linking Astro to WordPress

This segment outlines the pivotal step of connecting Astro to WordPress, focusing on API interactions and data presentation.

Secure API Authentication

Ensure WordPress credentials are securely stored for API communication.

WORDPRESS_URL=https://your-wordpress-url.com
WORDPRESS_USER=your-username
WORDPRESS_SECRET=your-password

Axios Client Setup

Demonstrates configuring Axios for API requests, adaptable to alternative libraries.

import axios from 'axios';

const config = {
  baseURL: import.meta.env.WORDPRESS_STAGING_URL + '/wp-json/wp/v2/',
  headers: {
    'Content-Type': 'application/json',
  },
  auth: {
    username: import.meta.env.WORDPRESS_USER,
    password: import.meta.env.WORDPRESS_SECRET,
  },
};

export const fetchApi = axios.create(config);

fetchApi.interceptors.request.use(
  (config) => config,
  (error) => Promise.reject(error)
);

Further exploration on fetching WordPress data within Astro will continue in Chapter 3.

Feel free to share questions or feedback in the comments section.

Introduction to Astro + WordPress

Marvin Bangemann — Tue, 20 Feb 2024 22:29:35 +0000

Introduction

Embarking on the development of a new Astro-based website, we've opted for WordPress, the world's leading CMS, to serve as our headless CMS. This decision stems from a detailed evaluation of our company's website needs and a desire to streamline our digital presence. Despite WordPress's ubiquity and its perceived complexity due to plugins and an extensive user base, its market dominance is undeniable. Our choice was driven by practical business considerations, recognizing WordPress's familiarity to our marketing team and its adaptability for future team members.

The Rationale Behind Choosing WordPress

Our selection of WordPress was a strategic business move. Its unparalleled market share speaks volumes about its efficacy and reliability. This choice, devoid of personal bias, is grounded in WordPress's extensive adoption and ease of use for our marketing team. This decision marks a step towards refining our current digital setup and leveraging the best of WordPress's capabilities.

Preliminary Steps and Considerations

In our quest to revamp the website, it was crucial to safeguard it against unintended alterations that could veer off our brand guidelines. To achieve this, we employed Advanced Custom Fields (ACF) to craft custom blocks, providing a controlled environment for the marketing team. This setup allows for content editing within predefined boundaries, ensuring both flexibility and adherence to our design and structural standards.

Technology Stack

Our project harnesses a robust suite of technologies, including:

Astro for the front-end framework, enabling a modern and efficient website interface.
WordPress as the backend headless CMS, offering a versatile content management foundation.
Advanced Custom Fields for creating custom content blocks, ensuring content consistency and design integrity.
Zod for robust type validation, enhancing code reliability.
Axios for streamlined API interactions, facilitating seamless data fetching.
TailwindCSS for utility-first styling, promoting design flexibility and ease of customization.

Learning Outcomes

By following this guide, you'll gain insights into:

Configuring WordPress as a headless CMS for enhanced content management and delivery.
Integrating Astro with WordPress to create a dynamic, content-driven website.
Managing site navigation within Astro, ensuring a seamless user experience.
Implementing Gutenberg Blocks within Astro, allowing for a rich content presentation.

This journey through setting up a WordPress-backed Astro website not only refines our digital footprint but also empowers our marketing team with a familiar yet powerful CMS, ensuring our online presence is both robust and easily manageable.