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
Details
Sample Project
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
- function which returns the component like
- 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