Mars Theme: A Deep Look at Frontity's Headless WordPress Theme

This article was started before Automattic's acquisition of Frontity and its team. Frontity's founders plan to transition the framework into a community-driven project, ensuring its stability, bug-free operation, and comprehensive documentation. Like other open-source projects, Frontity will remain free, offering opportunities for community contributions and enhancements. Further details are available in their FAQ.

My previous article detailed creating a headless WordPress site with Frontity and briefly examined its file structure. This article delves into the @frontity/mars-theme package (Mars Theme), providing a step-by-step guide to customization. The Mars Theme serves as an excellent starting point, being Frontity's default theme, similar to WordPress's Twenty Twenty-One.

We'll explore the core components of the Mars Theme, including its "building blocks," and examine the various components included in the package. We'll cover functionality, operation, and styling with practical examples.

Let's begin!

Table of Contents

• Introduction: Understanding Frontity's Building Blocks
• Section 1: Exploring the Mars Theme Structure
• Section 2: Utilizing the List Component
• Section 3: Links, Menus, and Featured Images
• Section 4: Styling a Frontity Project
• Section 5: Customizing the Frontity Mars Theme
• Section 6: Resources and Acknowledgements
• Conclusion: Final Thoughts and Reflections

Frontity's Fundamental Components

Let's revisit the Frontity project file structure from the previous article, highlighting Frontity's core components: frontity.settings.js, package.json, and the packages/mars-theme folder. The package.json file provides crucial project information, including name, description, author, and dependencies. Key packages include:

• frontity: The main package containing Frontity app development methods and the CLI.
• @frontity/core: Handles bundling, rendering, merging, transpiling, and serving. Direct access isn't typically needed for app development. A complete list is in the Frontity documentation.
• @frontity/wp-source: Connects to the WordPress REST API, fetching data for the Mars Theme.
• @frontity/tiny-router: Manages window.history and routing.
• @frontity/html2react: Converts HTML to React, using processors to replace HTML sections with React components.

Frontity's core, or @frontity/package (also called a "building block"), includes useful React component libraries in @frontity/components, exporting components like Link, Auto Prefetch, Image, Props, Iframe, Switch, and other functions and objects. Detailed descriptions and syntax information are in the package reference API.

The Frontity documentation explains the project startup process: All packages defined in frontity.settings.js are imported by @frontity/file-settings, and their settings and exports are merged by @frontity/core into a single store. This store allows access to the state and actions of different packages during development using @frontity/connect, Frontity's state manager.

Next, we'll examine how these building blocks are used within the Mars Theme to create a functional Frontity project with a headless WordPress endpoint.

Section 1: Understanding the Mars Theme Structure

Before customization, let's familiarize ourselves with the Mars Theme (@frontity/mars-theme) file structure:

<code>packages/mars-theme/
|__ src/
  |__ index.js
  |__ components/
     |__ list/
       |__ index.js
       |__ list-item.js
       |__ list.js
       |__ pagination.js
     |__ featured-media.js
     |__ header.js
     |__ index.js
     |__ link.js
     |__ loading.js
     |__ menu-icon.js
     |__ menu-model.js
     |__ menu.js
     |__ nav.js
     |__ page-error.js
     |__ post.js
     |__ title.js</code>

The Mars Theme's key components are: /src/index.js, src/list/index.js, and src/components/index.js. The Frontity documentation provides detailed explanations of how these components are defined and interconnected. Let's focus on the three most important: Root, Theme, and List.

Theme Root Component (/src/index.js)

The src/index.js file (the theme's Root) is crucial. It serves as the entry point, targeting a <div> in the site markup to inject the roots of all installed packages. A Frontity theme exports a <code>root and other necessary packages into the DOM. The Frontity documentation illustrates this using Slot and Fill extensibility patterns. An example from the Mars Theme package shows how it initializes the Root component:

// mars-theme/src/components/index.js
// ... (code omitted for brevity) ...

The Root component exports packages including roots, fills, state, actions, and libraries. More details on the Root component are in the Frontity documentation.

Theme Component (/src/components/index.js)

The Frontity Theme component is the main root-level component exported by the Theme namespace. It's wrapped with the @frontity/connect function, providing access to state, actions, and libraries props. This allows the Theme component to read the state, use actions, and utilize code from other packages.

// mars-theme/src/components/index.js
// ... (code omitted for brevity) ...

This example, from the Mars Theme's /src/components/index.js, uses state.source.get() to retrieve data for rendering components like List and Post.

Section 2: Working with the List Component

The previous section covered theme-level components. Now, let's examine a specific component: List.

The List component is exported by src/components/list/index.js, using @loadable/components for code splitting. The component loads only when a user views a list; it doesn't render when viewing a single post.

Displaying Lists of Posts

The src/components/list/list.js component renders lists of posts using state.source.get(link) and its items field.

// src/components/list/list.js
// ... (code omitted for brevity) ...

The connect function provides access to the global state. list-item.js and pagination.js are also imported.

Paginating a List of Posts

The Pagination component (src/components/list/pagination.js) allows users to navigate between pages of posts.

// src/components/list/pagination.js
// ... (code omitted for brevity) ...

The connect function grants access to the global state and actions.

Displaying Single Posts

The Post component displays single posts and pages. The structure is similar, except posts include metadata (author, date, categories, etc.).

// src/components/post.js
// ... (code omitted for brevity) ...

Conditional rendering ensures metadata is displayed only for posts, and featured images are shown based on theme settings.

Section 3: Links, Menus, and Featured Images

The List component is crucial for displaying posts. Let's examine other essential components.

The Link Component (src/components/link.js)

The MarsLink component (src/components/link.js) is a wrapper around the @frontity/components/link component.

// src/components/link.js
// ... (code omitted for brevity) ...

It includes a handler to close the mobile menu when a link is clicked.

Frontity Menu (src/components/nav.js)

The Nav component (src/components/nav.js) iterates over menu items defined in frontity.settings.js or the Frontity state, matching URLs and displaying components within the Header.

// src/components/nav.js
// ... (code omitted for brevity) ...

The connect function provides access to the state. Additional menu components (menu.js and menu-modal.js) are provided for mobile views.

Featured Image Component (/src/components/featured-media.js)

Featured media is defined in the Root component's theme.state.featured. The full code is in /src/components/featured-media.js.

Section 4: Styling a Frontity Project

Styling in Frontity differs from WordPress. Frontity provides reusable components built with styled-components and Emotion, a CSS-in-JS library.

Using styled-components

Styled-components are created using Emotion's styled function. For example:

// Creating Button styled component
import { styled } from "frontity";

const Button = styled.div`
  background: lightblue;
  width: 100%;
  text-align: center;
  color: white;
`;

Using a CSS prop

The css prop allows inline styling using template literals.

/* Using as CSS prop */
import { css } from "frontity";

const PinkButton = () => (
  <div css="{css`background:" pink>
    My Pink Button
  </div>
);

Using the <global></global> component

The <global></global> component applies site-wide styles.

// ... (code omitted for brevity) ...

Section 5: Customizing the Frontity Mars Theme

This section demonstrates customizing the Mars Theme. (Detailed examples and code snippets omitted for brevity; refer to the original response for complete code examples.) Key customizations include:

• Renaming the theme package.
• Refactoring navigation with dynamic menu fetching (using the WP-REST-API V2 Menus plugin).
• Modifying the file structure for better organization.
• Adding a custom footer component.
• Customizing the theme header.
• Adding <global></global> style components.
• Implementing fluid typography.
• Adding webfonts.
• Styling pages and posts (including Gutenberg block styles).

Section 6: Resources and Acknowledgements

(List of resources and credits omitted for brevity; refer to the original response for the complete list.)

Conclusion: Final Thoughts and Reflections

This exploration of Frontity and its Mars Theme highlights its beginner-friendliness, low maintenance, and compatibility with experimental block themes. However, the current hosting costs and areas for documentation improvement are noted. Further exploration of headless site development using Gatsby and Frontity, along with the evolution of WordPress block themes, is planned.