Made in Builder

Made in Builder.io

Live Demo ๐Ÿ‘‰ All Demo, No Pitch: Content & Commerce / Builder.io & Elastic Path on 12/13

ร—

Developers

Product

Use Cases

Pricing

Developers

Resources

Company

Get StartedLogin

โ˜ฐ

Product

Features

Integrations

Talk to an Expert

Pricing

Blog

Home

Resources

Blog

Forum

Github

Login

Signup

ร—

Visual CMS

Drag-and-drop visual editor and headless CMS for any tech stack

Theme Studio for Shopify

Build and optimize your Shopify-hosted storefront, no coding required

Resources

Blog

Get StartedLogin

โ˜ฐ

Making a Plugin

You can extend and customize Builder by making your own plugin. With custom plugins you can register custom field types for your Builder model custom fields and inputs for your custom components, custom targeting or symbols.

This document covers making a minimal plugin to add a custom type for use in a Data model.

Tip: All plans can create and submit Builder Plugins. When you're ready to contribute your plugin, head over to GitHub and submit a PR. Make sure to add your plugin to the plugins directory.

Prerequisites

To get the most out of this document, make sure you are familiar with the following:

Extending the UI with custom types

This tutorial guides you through creating a plugin with a custom type and custom type editor. By creating custom types in a plugin, you provide rich data types that you can use across the Visual Editor. For example, you can:

  • Create custom component inputs that accept structured data fields
  • Target content based on products in a customer's cart
  • Model fields that store multimedia content
  • Enable Symbol inputs to accept externally hosted documents

Each custom type has a custom type editor, which provides a user interface for selecting values for your custom type fields. For example, editors can fetch external resources and present the user with a browsable list of items or provide menus and fields for data entry.

With custom types and custom type editors, your users can create and update nearly any kind of data structure beyond the basic types provided by Builder, all from within the Visual Editor.

After installing the plugin that registers your custom type editor, the corresponding custom type is available across the Visual Editor, specifically when using the following features:

  • Custom component inputs
  • Targeting content
  • Model fields
  • Symbol inputs

Step 1: Create project and install dependencies

Create a directory for your plugin and open the new director with the following command:

Initialize the project to use npm:

Press Enter through the prompts and respond yes to the proposed package.json.

Use npm install to install the dependencies for this project. You can use --save-dev because Builder provides these dependencies for you later. The dependencies are:

  • @builder.io/app-context: exposes certain APIs to interact with APIs to interact with Builder
  • @builder.io/react: enables you to use React to create your plugin
  • webpack: module bundler for JavaScript
  • webpack-dev-server: development server with live reloading
  • @babel/preset-react: supports JSX
  • babel-loader: transpiles modern and superset JavaScript, such as JSX using Babel with webpack

Paste the following command, which includes all these dependencies, at the command line:

Install react-quill for the Rich Text editor that this plugin uses:

Step 2: Set up the files

This section guides you through creating the project infrastructure by creating the key files and pasting in the contents for each.

Replace the contents of package.json with the following:

At the root of your project, create a file called .babelrc and paste in the following:

Again at the root of your project, create a file called webpack.config.js and paste in the following:

This file establishes these key configurations:

  • The location of the entry point, or where webpack starts when bundling. Here, it's plugin.jsx.
  • The externals are dependencies that you don't need to bundle. You don't need to bundle them because when your plugin is ready, Builder provides these dependencies for you.
  • resolve.extensions specifies that you're using JavaScript and JSX files. If you're using other file extensions, add them here.
  • The module settings specify that you're using JSX files, not bundling node_modules, and using babel-loader to work with JSX.
  • With devServer, configures your plugin to run locally on localhost:1268, serve from the ./dist directory, and provides headers for local development with Builder.

Tip: You can also pass data into your plugin when registering it as an input type. This is useful if you want to control things like API keys or settings in your own codebase, but want to be able to pass into the plugin whenever it is used. To do this, use the options property when registering an input for a component. For more detail, see this example on GitHub from an async dropdown plugin.

Step 3: Create the plugin

Create a folder called src with a file called plugin.jsx and paste in the following:

The key points in the example above are:

  • The editor component wraps ReactQuill, which in turn takes onChange and value as props. The value you set can be any type serializable to JSON, such as string, number, null, array, or object, and be as deeply nested as you need. Refer to the react-quill documentation for more information.
  • props.onChange and props.value are passed to the editor component, which controls the editor's state. value is the current value of the field. onChange is a callback function that accepts one parameter, which is the field's new value after the user changes that value within the editor. For more information, see Controlled Components in the React documentation.
  • When the user updates the text area provided by ReactQuill, ReactQuill calls onChange, which updates the editor's state.
  • Updating the editor's state updates props.value, which is passed down to ReactQuill to update that component's internal state.
  • Registering the editor component with Builder.registerEditor() creates the MyText custom type.

Builder.registerEditor() accepts one parameter: an options object with three properties:

  • name: a string, typically camel-cased, that represents the custom type's name
  • component: the editor component
  • options (optional): an object

Tip: When developing locally, you are mostly likely developing on a non-ssl http:// url within Builder, which is an https:// site. Browsers don't allow https:// sites to make insecure http:// requests unless you explicitly allow it. To allow access to your local http URL in Chrome, click the shield icon on the right side of the address bar, and choose load unsafe scripts. The page will reload and you might have to enter your local URL a second time for Chrome to allow its content to load.

For more information on input types, see Input Types for Custom Components.

Step 4: Add your plugin to Builder

  1. Go to Account Settings.
  2. Click the pencil icon for Plugins to add the plugin.
  3. Enter the local address for this example plugin: http://localhost:1268/plugin.system.js.
  4. Click the Save button.

The following video shows these steps:

Step 5: Use your plugin in Builder

  1. Go to Models.
  2. Select a model to edit or create a new one.
  3. In the model, click the + New Field button.
  4. To confirm that your plugin is working, click the Type dropdown and scroll down to select the type MyText. Notice that when you select MyText, the Default value input changes to a Rich Text input that includes text formatting options.

MyText comes from the name you provided in plugin.jsx. to Builder.registerEditor(). The following video shows these steps:

Next steps

This tutorial showed you how to create a minimal plugin and use it locally. When you've created your plugin, you can do one of two things:

  • Get your unique plugin creations added to Builder, by check us out on GitHub and submitting a PR with your plugin on the Builder.io repo.
  • If you're on an Enterprise plan, you can instead host your plugin yourself as a private plugin. For more information, see Creating a Private Plugin.



Looking to hire a 3rd party to help with your project?

Submit a project request and our partnerships team will reach out to connect you with an Expert from our partner ecosystem.

Connect with us

Was this article helpful?