@gravityforms/components/html/admin/elements/StackedIcon/index.js

UI components for use in Gravity Forms development. Both React and vanilla js flavors.

import {
	consoleInfo,
	getNode,
	objectToAttributes,
	spacerClasses,
	trigger,
	uniqueId,
} from '@gravityforms/utils';

/**
 * @function stackedIconTemplate
 * @description Generates the markup for a stackedIcon in the admin.
 *
 * @since 1.1.16
 *
 * @param {object}                     options                  The options for the component template.
 * @param {object}                     options.customAttributes Any custom attributes.
 * @param {Array}                      options.customClasses    An array of additional classes for the toggle.
 * @param {string}                     options.id               Id for the stackedIcon, auto generated if not passed.
 * @param {string|number|Array|object} options.spacing          The spacing for the component, string, number, object or array.
 * @param {string}                     options.tagName          Tag to use for the icon wrapper. Defaults to 'span',
 * @param {string}                     options.theme            Theme for the toggle, primary or cosmos.
 * @param {string}                     options.type             The icon name string.
 *
 * @return {string}
 * @example
 * import { stackedIconTemplate } from '@gravityforms/components/html/admin/elements/StackedIcon';
 *
 * function Example() {
 *      const stackedIconTemplateHTML = stackedIconTemplateTemplate( options );
 *      document.body.insertAdjacentHTML( 'beforeend', stackedIconTemplateHTML );
 * }
 *
 */
export const stackedIconTemplate = ( {
	customAttributes = {},
	customClasses = [],
	id = '',
	spacing = '',
	tagName = 'span',
	theme = 'primary',
	type = '',
} ) => {
	const componentAttrs = objectToAttributes( {
		...customAttributes,
		id,
		class: [
			'gform-st-icon',
			`gform-st-icon--theme-${ theme }`,
			`gform-st-icon--${ type }`,
			...Object.keys( spacerClasses( spacing ) ),
			...customClasses,
		],
	} );

	return `
		<${ tagName } ${ componentAttrs }></${ tagName }>
	`;
};

/**
 * @class StackedIcon
 * @description A stackedIcon component .
 *
 * @since 1.1.16
 *
 * @borrows stackedIconTemplate as stackedIconTemplate
 *
 * @param {object} options                  The options for the component.
 * @param {object} options.customAttributes Any custom attributes for the component.
 * @param {Array}  options.customClasses    An array of additional classes for the component.
 * @param {string} options.id               Id for the component, auto generated if not passed.
 * @param {string} options.rendered         Is the component already rendered in the dom, eg by php?
 * @param {string} options.renderOnInit     Render the component on init of the class?
 * @param {string} options.spacing          Spacing for the component.
 * @param {string} options.target           The target to render to. Any valid css selector string.
 * @param {string} options.targetPosition   The insert position for the component relative to the target.
 * @param {string} options.theme            Theme for the component, primary or cosmos.
 *
 * @return {Class} The class instance.
 * @example
 * import StackedIcon from '@gravityforms/components/html/admin/elements/StackedIcon';
 *
 * function Example() {
 *      const stackedIconInstance = new StackedIcon( {
 *          id: 'example-stackedIcon',
 *          renderOnInit: false,
 *          target: '#example-target',
 *          targetPosition: 'beforeend',
 *          theme: 'cosmos',
 *      } );
 *
 *      // Some time later we can render it. This is only done if we set renderOnInit to false.
 *      // If true it will render on initialization.
 *      stackedIconInstance.init();
 * }
 *
 */
export default class StackedIcon {
	constructor( options = {} ) {
		this.options = {};
		Object.assign(
			this.options,
			{
				customAttributes: {},
				customClasses: [],
				id: '',
				rendered: false,
				renderOnInit: true,
				spacing: '',
				target: '',
				targetPosition: 'afterbegin',
				theme: 'cosmos',
			},
			options
		);

		/**
		 * @event gform/stacked_icon/pre_init
		 * @type {object}
		 * @description Fired before the component has started any internal init functions. A great chance to augment the options.
		 *
		 * @since 1.1.16
		 *
		 * @property {object} instance The Component class instance.
		 */
		trigger( { event: 'gform/stacked_icon/pre_init', native: false, data: { instance: this } } );

		this.options.id = this.options.id || uniqueId( 'toggle' );

		this.elements = {};

		if ( this.options.renderOnInit ) {
			this.init();
		}
	}

	/**
	 * @memberof StackedIcon
	 * @description Renders the component into the dom.
	 *
	 * @since 1.1.16
	 *
	 * @return {void}
	 */
	render() {
		const { rendered, target, targetPosition } = this.options;

		if ( ! rendered ) {
			const renderTarget = getNode( target, document, true );

			renderTarget.insertAdjacentHTML(
				targetPosition,
				stackedIconTemplate( this.options )
			);
		}

		this.elements.stackedIcon = getNode( `#${ this.options.id }`, document, true );
	}

	/**
	 * @memberof StackedIcon
	 * @description Initialize the component.
	 *
	 * @fires gform/stacked_icon/post_render
	 *
	 * @since 1.1.16
	 *
	 * @return {void}
	 */
	init() {
		this.render();

		/**
		 * @event gform/stacked_icon/post_render
		 * @type {object}
		 * @description Fired when the component has completed rendering and all class init functions have completed.
		 *
		 * @since 1.1.16
		 *
		 * @property {object} instance The Component class instance.
		 */
		trigger( { event: 'gform/stacked_icon/post_render', native: false, data: { instance: this } } );

		consoleInfo( `Gravity Forms Admin: Initialized stackedIcon component.` );
	}
}