Gravity Forms Components

The Gravity Forms component library, for both HTML and React components. This is used for our new UI's in both the WordPress admin and some of the front end.

The HTML components are built as plain es6 classes which also export a template function when you don't need a stateful instance.

The React components are standard hooks based functional components using React 18. They depend on our own Libraries package, which - if being used in the WordPress environment with Gravity Forms active - can be enqueued from that plugin for the production bundle.

This package also contains compiled files you can enqueue yourself, with a custom global namespace override you can use. Parsed css partials are also supplied if you wish to build your own custom css file and be independent of Gravity Forms. Detailed instructions in the usage section.

Installation

Install the module

npm install @gravityforms/components

Usage

Using Component Exports In Your Own Bundles

This package is delivered as es6 modules, you probably want your webpack or other bundling system to run it through babel with @babel/preset-react active.

In the case of webpack and babel, this means adding it to your exclude property of the rules array in the module object, like so:

const config = {
	// other config
	module: {
		rules: [
			{
				test   : /\.js$/,
				exclude: [ /node_modules\/(?!(@gravityforms)\/).*/ ],
				use    : [
					{
						loader: 'babel-loader',
					},
				],
            }
        ],
	},
}

Using The Dependency Extraction Plugin

We have a WebPack plugin that extends the WordPress dependency extraction plugin at @gravityforms/dependency-extraction-webpack-plugin. If you want to use this to map to the externals we supply with the Gravity Forms plugin, simply use that plugin in your WebPack config and enqueue gform_gravityforms_admin_components to get the whole stack needed to use our admin components off our globals when not in development.

Enqueuing Gravity Forms CSS

If you are just mapping to our externals and/or using the js directly and are using this in a Gravity Forms add-on, you can just ensure that our css is enqueued. The admin components css handle is gform_admin_components.

Creating A Custom CSS File

Css for the components is included in the package at dist/css/. There is a file for each component, and they style both the react and html components. You probably want to glob together all the components you use and build a single css file for your project.

Each component relies on a wrapper css class for its styles to take effect. By default, these files ship with .gform-admin or .gform-theme as the wrapper class. If you want to avoid collisions with Gravity Forms core, use a search and replace of some kind to swap that out for your own wrapper class during the glob.

Enqueuing the Compiled JavaScript Files

Do this only if you wish to not use the files enqueued by Gravity Forms.

All javascript files at the root of dist/js should be copied to a location in your plugin for enqueuing. By default, the components put themselves on the window.gform namespace. This would collide with the Gravity Forms globals, so we need to modify that namespace. This is done by setting window.gformComponentNamespace to the namespace of your choice. You also need to let webpack know where the files live for your plugin by setting window.gformComponentDistPath to the URI for the folder containing these files.

Example:

$mynamespace_namespace_script = 'var gformComponentNamespace = "mynamespace"; var gformComponentDistPath = "https://my/path/to/assets/js/dist/";';
wp_add_inline_script( 'mynamespace_gravityforms_libraries', $mynamespace_namespace_script, 'before' );

The components package relies on our libraries, react-utils and utils packages, which is why you see the inline script above being output before 'mynamespace_gravityforms_libraries'. You will also have to copy those three files from their respective packages in the @gravityforms folder in your node_modules.

They will all be located in the dist directory of those packages. Here is the required enqueues in the order they need to be in for the admin components:

'mynamespace_gravityforms_libraries'
'mynamespace_gravityforms_utils'
'mynamespace_gravityforms_react_utils'
'mynamespace_gravityforms_admin_components'

Also, use exactly these handles, as, if using our dependency extraction plugin, these tie in with that.

If you are using @gravityforms/dependency-extraction-webpack-plugin with this custom setup, remember to pass mynamespace to it in its ooptions as rootNamespace. Check its docs for more details.

Documentation

The documentation for this package is available at http://docs.js.gravity.com/