This guide covers how to customize your site’s Toolbar utilizing the toolbarNodes filter.

Prerequisites

• Getting Started Guide
• Authorization

Step 1: Add the Toolbar to your project

NOTE
The Toolbar is currently an experimental feature that was introduced in @faustwp/core@0.2.5.

Add styles

The (Faust) Toolbar shares mostly the the same HTML as the WordPress core Toolbar. This enables the use of the same styles that exist in WordPress core, and have been converiently provided for you to import within @faustwp/core.

// pages/_app.js

import '@faustwp/core/dist/css/toolbar.css';
Code language: JavaScript (javascript)

Enable toolbar

Add experimentalToolbar: true to your project’s faust.config.js.

// faust.config.js

import { setConfig } from '@faustwp/core';
import templates from './wp-templates';
import possibleTypes from './possibleTypes.json';

export default setConfig({
  experimentalToolbar: true, // Enable experimental toolbar
  templates,
  possibleTypes,
});
Code language: JavaScript (javascript)

Login to your site

The Toolbar was designed to only load for the authenticated user.

NOTE
A WordPress user will be automatically authenticated with your site when previewing a post. This approach can be used as a quick way view the Toolbar for development purposes.

See Authentication for more details about implementing auth within Faust.

Step 2: Create the plugin

Create a new file in your Faust project: plugins/CustomPlugin.tsx.

Add the following code to plugins/CustomPlugin.tsx.

//plugins/CustomPlugin.tsx

import React from 'react';
import {
  FaustHooks,
  FaustPlugin,
  FaustToolbarNodes,
  FaustToolbarContext,
  ToolbarItem,
  ToolbarSubmenu,
  ToolbarSubmenuWrapper,
} from '@faustwp/core';

/**
 * Example Custom Toolbar Plugin.
 */
export class CustomToolbar implements FaustPlugin {
  apply(hooks: FaustHooks) {
    /**
     * This example demonstrates how to filter on the core Toolbar nodes
     * in order to add your own custom nodes!
     */
    hooks.addFilter(
      'toolbarNodes',
      'faust',
      (toolbarNodes: FaustToolbarNodes, context: FaustToolbarContext) => {
        const customToolbarNodes: FaustToolbarNodes = [
          {
            id: 'custom-node',
            location: 'primary',
            component: <CustomNode />,
          },
          {
            id: 'custom-node-with-submenu',
            location: 'primary',
            component: <CustomNodeWithSubmenu />,
          },
        ];

        return [...toolbarNodes, ...customToolbarNodes];
      },
    );
  }
}

/**
 * A simple link.
 */
export function CustomNode() {
  return (
    <ToolbarItem href="https://wpengine.com" rel="nofollow">
      Custom Node
    </ToolbarItem>
  );
}

/**
 * A simple link with a submenu that displays on hover.
 */
export function CustomNodeWithSubmenu() {
  return (
    <>
      <ToolbarItem href="https://wpengine.com" rel="nofollow">
        Custom Node w/ Submenu
      </ToolbarItem>
      <ToolbarSubmenuWrapper>
        <ToolbarSubmenu>
          <li>
            <ToolbarItem href="https://wpengine.com" rel="nofollow">
              Link
            </ToolbarItem>
          </li>
          <li>
            <ToolbarItem href="https://wpengine.com" rel="nofollow">
              Link
            </ToolbarItem>
          </li>
          <li>
            <ToolbarItem href="https://wpengine.com" rel="nofollow">
              Link
            </ToolbarItem>
          </li>
        </ToolbarSubmenu>
      </ToolbarSubmenuWrapper>
    </>
  );
}
Code language: JavaScript (javascript)

Step 3: Register The Plugin

NOTE:
experimentalPlugins is being deprecated and replaced with plugins in the faust.config.js file. Please update your configuration accordingly.

Import and register your new plugin in faust.config.js.

// faust.config.js

import { setConfig } from '@faustwp/core';
import templates from './wp-templates';
import possibleTypes from './possibleTypes.json';
import { CustomToolbar } from './plugins/CustomPlugin.tsx';

export default setConfig({
  templates,
  experimentalToolbar: true,
  plugins: [new CustomToolbar()], // Register plugin
  possibleTypes,
});Code language: JavaScript (javascript)

You should now be able to see your new Custom Nodes.