Register Grouped Format Type

Read this in other languages: English, 日本語.

This is a Gutenberg's library to provides method to register grouped RichText format types,
which will be gathered by DropDown when number of format type of same group is greater than 1.
The controls are active only when it is able to toggle format.

Table of Contents

Sample Project

Gutenberg Samples

Usage

yarn add @technote-space/register-grouped-format-type

e.g. assets/register.js

import { RichText } from '@technote-space/register-grouped-format-type';
import { Helpers } from '@technote-space/gutenberg-utils';

const { registerGroupedFormatType } = RichText;
const { getToolbarButtonProps } = Helpers;

/** register grouped format types
*
* - test1 (⇒ not dropdown)
*     |- format-test1
* 
* - test2 (⇒ dropdown)
*     |- format-test2
*     |- format-test3
*/
registerGroupedFormatType( getToolbarButtonProps( 'test1', 'format-test1', 'admin-customizer' ) );
registerGroupedFormatType( getToolbarButtonProps( 'test2', 'format-test2', 'admin-customizer' ) );
registerGroupedFormatType( getToolbarButtonProps( 'test2', 'format-test3', 'admin-customizer' ) );

<script type="text/javascript" src="/assets/register.js"></script>

Use group setting

You can customize dropdown settings such as icon, label, position, and so on.

import { RichText } from '@technote-space/register-grouped-format-type';

const { registerFormatTypeGroup } = RichText;

// register format type group setting
registerFormatTypeGroup( 'test2', {
	icon: 'admin-network',
} );

Use inspector

import { RichText } from '@technote-space/register-grouped-format-type';
import { Helpers } from '@technote-space/gutenberg-utils';

const { registerFormatTypeGroup, registerGroupedFormatType, getRemoveFormatButton } = RichText;
const { getColorButtonProps, getFontSizesButtonProps } = Helpers;

// register format group for inspector
registerFormatTypeGroup( 'inspector', {
	inspectorSettings: {
		title: 'test inspector',
		initialOpen: true,
	},
	// set useContrastChecker = true to show ContrastChecker
	useContrastChecker: true,
	// set additional inspector (function: args => component)
	additionalInspectors: [ getRemoveFormatButton( 'remove all formats' ) ],
} );

// register format type
registerGroupedFormatType( getColorButtonProps( 'inspector', 'font-color', 'Font Color', 'admin-site', 'color' ) );
registerGroupedFormatType( getColorButtonProps( 'inspector', 'background-color', 'Background Color', 'editor-textcolor', 'background-color' ) );
registerGroupedFormatType( getFontSizesButtonProps( 'inspector', 'font-size', 'Font Size', 'edit' ) );

Functions

registerGroupedFormatType

Register grouped format type.

definition

/**
 * @param {string} name name
 * @param {string} title title
 * @param {string} tagName tag name
 * @param {string} className class name
 * @param {function?} create create component function
 * @param {function?} createInspector create inspector component function
 * @param {string?} group group
 * @param {string?} inspectorGroup inspector group
 * @param {object} settings settings
 * @return {object|null} registered settings
 */
registerGroupedFormatType( {
	name,
	title = name,
	tagName = 'span',
	className = name,
	create,
	createInspector,
	group = name,
	inspectorGroup,
	...settings
} )

arguments

• name (required)
  • format name
  • detail
• title
  • format title
  • detail
• tagName
  • tag name
  • detail
• className
  • class name
  • detail
  • You can use multiple classes (space separated).
• create (required)
  • function which returns the component like ToolbarButton
• group (required)
  • group name
  • When the number of items in the same group is more than 1, they will be gathered by DropDown.

registerFormatTypeGroup

Register group settings of format type.

definition

/**
 * @param {string} name group name
 * @param {object} setting setting
 * @returns {object} registered setting
 */
registerFormatTypeGroup( name, setting = {} )

arguments

• name (required)
  • group name
• setting
  • group setting

default setting

{
	icon: 'admin-customizer',
	position: 'top right',
	label: name,
	className: undefined,
	menuClassName: undefined,
	inspectorSettings: {},
	toolbarGroup: undefined,
	useContrastChecker: false,
	additionalInspectors: [],
}

WP Dependencies

• wp-block-editor
• wp-components
• wp-data
• wp-element
• wp-i18n
• wp-hooks
• wp-rich-text
• wp-url
• lodash

Dependency

Gutenberg Utils

Author

GitHub (Technote)
Blog