Frontly Toolbar API

toolbar.md

Toolbar API

Create toolbar buttons which can be assigned to elements. Toolbars appear when elements are hovered on.

Table of Contents

• Register a toolbar button
  • The params object
  • The onClick parameter
  • The render parameter
• Unregistering a toolbar button
• Get all registered toolbar buttons
• Get a registered toolbar button
• Get the toolbar buttons of an element
• Set the toolbar buttons of an element

Register a toolbar button

frontly.registerToolbarButton( String name, Object params )

Description

This registers a single toolbar button.

Parameters

Parameter	Description
name	The unique ID of the toolbar button.
params	Contains the parameters of the toolbar button. Please see below for a better explanation of this parameter.

The params object

// Minimum params.
{
	onClick: ( props ) => {
		console.log( 'clicked!' )
	},
}

Property	Type	Description
icon	Component	The icon to display on this button. If no icon is given, this defaults to a gear icon.
render	Function	A custom render function that should return a Component. If you use this, the output of this render function will be used instead of displaying a button with an icon, you will also be in charge of performing your own click handler/s.
onClick	Function	Called when the button is clicked.

The onClick parameter

The onClick parameter takes a function callback. This is called when the toolbar button is clicked.

An object containing the following properties are passed to the function:

Parameter	Type	Description
attributes	Array	An array of the current attributes of the element.
setAttributes	Function	See the documentation on the setAttributes function.
clone	Function	Creates a clone of the current element.
remove	Function	Removes the current element.

The render parameter

Use the render parameter to completely override the toolbar button rendering. Note that this is a blank button, you will be in charge of what will be shown and how interactions are handled.

An object containing the following properties are passed to the render function:

Parameter	Type	Description
className	String	The classes that should be added into the container of the toolbar button.
onClick	Function	This function is the onClick parameter passed to the params object above. It is supplied to the render function so that you can handle the click event.
Also includes all the parameters from the onClick parameter.

Examples

Regular toolbar button with a custom icon

const icon = (
	<svg>...</svg>
)
frontly.registerToolbarButton( 'mybutton', {
	icon: icon,
	onClick: ( props ) => {
		props.setAttributes( {
			backgroundColor: 'transparent',
		} )
	}
} )

Custom toolbar button

frontly.registerToolbarButton( 'mycustombutton', {
	render: ( props ) => {
		const { className, onClick } = props
		return (
			<div
				className={ className }
				onClick={ onClick }
				>
				My Label
			</div>
		)
	},
	onClick: ( props ) => {
		// This will be called by the onClick of the render function above.
		console.log( 'Do something!' )
	},
} )

Unregistering a toolbar button

Object frontly.unregisterToolbarButton( String element, String name )

Description

Unregisters a toolbar button.

Parameters

Parameter	Description
name	The name of the registered toolbar button.

Returns

The parameters of the unregistered toolbar button. Returns undefined if the button was not found.

Example

Unregister a toolbar button

frontly.unregisterToolbarButton( 'mybutton' )

Get all registered toolbar buttons

Array frontly.getToolbarButtons()

Description

Gets all the registered toolbar buttons.

Returns

An array containing the parameters of the registered toolbar buttons.

Get a registered toolbar button

Object frontly.getToolbarButton( String name )

Description

Gets a specific registered toolbar button.

Parameters

Parameter	Description
name	The name of the toolbar button.

Returns

The parameters of the toolbar button. Returns undefined if the button cannot be found.

Get the toolbar buttons of an element

Array frontly.getElementToolbar( String element )

Description

Gets the toolbar buttons assigned to an element.

Parameters

Parameter	Description
element	The name of the element.

Returns

An array of the toolbar button names currently assigned to the element.

Set the toolbar buttons of an element

frontly.setElementToolbar( String element, Array toolbarButtons )

Description

Assigns toolbar buttons to an element. This can only be changed before the editor has initialized.

Parameters

Parameter	Description
element	The name of the element.
toolbarButtons	An array of toolbar button names.