{"id":3131,"date":"2021-01-09T17:27:22","date_gmt":"2021-01-10T00:27:22","guid":{"rendered":"https:\/\/blocksylaunch.click\/documentation\/?p=3131"},"modified":"2021-01-09T17:27:22","modified_gmt":"2021-01-10T00:27:22","slug":"how-to-create-a-custom-field-for-a-divi-builder-module","status":"publish","type":"post","link":"https:\/\/blocksylaunch.click\/documentation\/developers\/how-to-create-a-custom-field-for-a-divi-builder-module\/","title":{"rendered":"How To Create a Custom Field For a Divi Builder Module"},"content":{"rendered":"

Note:<\/strong> This tutorial series is intended for advanced users. At least a basic understanding of coding in PHP and JavaScript is required.<\/p><\/blockquote>\n

Custom Fields for Divi Module Settings<\/h2>\n

Creating a custom field for a Divi module is similar to creating a custom Divi module<\/a> in the Divi Builder. Both methods require some Javascript, HTML, & CSS code. However, to create a custom field for a module, there is no need for any PHP because you don\u2019t need to write a PHP class to render the HTML output on the frontend. The main component needed is a ReactJS component class that handles rendering the field inside of the Divi Builder. Then you can define the custom field on your module definition.<\/p>\n

In this tutorial, you\u2019ll learn how to create custom fields for a Divi Builder module that will be fully functional in the builder.<\/p>\n

Getting Started<\/h2>\n

Keep in mind. Custom Divi Builder fields must be implemented within a theme, child-theme, or Divi Extension. In this tutorial, we\u2019re going to create a custom field for a custom module in a Divi Extension.<\/p>\n

Also, this tutorial is a continuation of previous tutorials that have a specific setup already in place.<\/p>\n

If you haven\u2019t already done so, go ahead and do the following before you start this tutorial:<\/p>\n

    \n
  1. Create a Divi Extension<\/a><\/li>\n
  2. Create a Custom Module<\/a>.<\/li>\n<\/ol>\n

    Once done, you are ready to continue.<\/p>\n

    Run Yarn<\/h3>\n

    Before we can test our custom field later on in the Divi Builder we’ll need to compile the JSX code into regular JavaScript. To do that, we need to run yarn<\/code>. To do this, simply run the following command inside your plugin\u2019s directory:<\/p>\n

    yarn start<\/pre>\n
    IMPORTANT: Be sure that yarn start<\/code> is running in the root folder of your plugin. Furthermore, you should keep yarn start<\/code> running as you develop so that the files continue to compile successfully.<\/p>\n
    Upgrading Divi Scripts<\/h3>\n
    Custom Divi Builder Fields is a new feature and only available on divi-scripts version 1.0.2 above. So, if you want to add custom field on your existing extension, please upgrade your divi-scripts to version 1.0.2. You can do this by changing divi-scripts version on your  package.json<\/code> located at at the root of your extension directory.<\/p>\n
    \"custom<\/p>\n
    Then run yarn install<\/code> to update. You can also find a custom field example on this documentation here<\/a>.<\/p>\n
    Update Field Directory and File Names<\/h2>\n
    We\u2019ll get to update the code in our files in a bit. But before we can do that, we need to change the default directory and file names for our new custom field.<\/p>\n
    Look inside your extension\u2019s directory and locate the example custom field located at \/includes\/fields\/Input\/Input.jsx<\/code>. <\/p>\n
    \"custom<\/p>\n
    We\u2019ll use this as a starting point to create a custom input field. <\/p>\n
    First, rename the Input<\/code> directory to SimpleInput<\/code>. <\/p>\n
    Inside the directory (now named SimpleInput<\/code>), rename the file Input.jsx<\/code> to SimpleInput.jsx<\/code>. <\/p>\n
    The path to the file should now be includes\/fields\/SimpleInput\/SimpleInput.jsx<\/code><\/p>\n
    \"how<\/p>\n
    Update the Field File<\/h2>\n
    Open the SimpleInput.jsx<\/code> file and edit it as follows:<\/p>\n
    Update the React Component Class<\/h3>\n
    For our custom field to be available and fully functional inside the Divi Builder we must create a React Component<\/a> class that handles the rendering of our custom field based on its props<\/code>.<\/p>\n
    By default, the component class is named Input<\/code>. Change the name of the class Input<\/code> to SimpleInput<\/code>.  <\/p>\n
    Then change the name Input<\/code> to SimpleInput<\/code> at the bottom of the file to reflect the new name of our component class in order to be exported for use.<\/p>\n
    Also make sure to update the slug, input id, and input className to reflect the name of the new field.<\/p>\n
    (NOTE: Depending on the prefix id you chose when setting up your Divi Extension, you may see different names for the static slug, input id, input class, etc. This example has the prefix simp<\/code> which was chosen when creating the Divi Extension.)<\/p>\n
    \"custom<\/p>\n
    Here is an example of what the code should look like after the change has been made:<\/p>\n
    \r\n\/\/ External Dependencies\r\nimport React, { Component } from 'react';\r\n\r\n\/\/ Internal Dependencies\r\nimport '.\/style.css';\r\n\r\nclass SimpleInput extends Component {\r\n\r\n  static slug = 'simp_simple_input';\r\n\r\n  \/**\r\n   * Handle input value change.\r\n   *\r\n   * @param {object} event\r\n   *\/\r\n  _onChange = (event) => {\r\n    this.props._onChange(this.props.name, event.target.value);\r\n  }\r\n\r\n  render() {\r\n    return(\r\n      <input\r\n        id={`simp-simple-input-${this.props.name}`}\r\n        name={this.props.name}\r\n        value={this.props.value}\r\n        type='text'\r\n        className='simp-simple-input'\r\n        onChange={this._onChange}\r\n        placeholder='Your text here ...'\r\n      \/>\r\n    );\r\n  }\r\n}\r\n\r\nexport default SimpleInput;\r\n<\/pre>\n
    The _onChange()<\/code> prop is a method handler to save or remove the field setting\u2019s value. It passes 2 parameters.<\/p>\n
    \"custom<\/p>\n
    The first parameter is the field setting\u2019s name. You can use name<\/code> prop here because it\u2019s already supplied with the correct field name based on the current active tab mode. For example: when you are editing the Title option in Tablet tab mode, the field\u2019s name generated is title_tablet<\/code>. The second parameter is the field setting value that you want to save. <\/p>\n
    The field setting type<\/strong> is actually a third parameter that is automatically defined with the current field type prop. So we don\u2019t have to include that parameter with the other 2.<\/p>\n
    Update the index.js file for the Custom Field<\/h2>\n
    Next, let\u2019s update the import and export statements in the index.js<\/strong> file located at \/includes\/fields\/index.js<\/code>. To do this, open to edit the index.js<\/strong> file.<\/p>\n
    Replace all instances of the name for the class and directory (which is Input<\/code> by default) to the new name SimpleInput<\/code>.<\/p>\n
    \"custom<\/p>\n
    Here is an example of the final code:<\/p>\n
    \r\nimport SimpleInput from '.\/SimpleInput\/SimpleInput';\r\n\r\nexport default [SimpleInput];\r\n<\/pre>\n
    Custom Field CSS Styles<\/h2>\n
    Styles for our custom field can be defined using the style.css<\/strong> file in its directory located at \/includes\/fields\/SimpleInput\/style.css<\/code>. <\/p>\n
    \"how<\/p>\n
    Our custom field is only a basic input element that comes with default builder styling. For now, let\u2019s change the default class selector to .simp-simple-input<\/code> (rendered in SimpleInput.jsx<\/strong>) throughout the style.css file:<\/p>\n
    \r\ninput.simp-simple-input {\r\n  background: #f1f5f9;\r\n  max-height: 30px;\r\n  border: 0;\r\n  border-radius: 3px;\r\n  padding: 7px 10px;\r\n  box-sizing: border-box;\r\n  transition: background 200ms ease;\r\n  color: #4C5866;\r\n  font-family: 'Open Sans', Helvetica, Roboto, Arial, sans-serif;\r\n  font-size: 13px;\r\n  font-weight: 600;\r\n  line-height: normal;\r\n  display: block;\r\n  width: 100%;\r\n}\r\n\r\ninput.simp-simple-input:focus {\r\n  background: #e6ecf2;\r\n}\r\n\r\ninput.simp-simple-input::-webkit-input-placeholder {\r\n  color: #98a7b8;\r\n}\r\n\r\ninput.simp-simple-input:-moz-placeholder {\r\n  color: #98a7b8;\r\n}\r\n\r\ninput.simp-simple-input::-moz-placeholder {\r\n  color: #98a7b8;\r\n}\r\n\r\ninput.simp-simple-input:-ms-input-placeholder {\r\n  color: #98a7b8;\r\n}\r\n\r\ninput.simp-simple-input[readonly] {\r\n  background: #ffffff !important;\r\n  border: 1px solid #eaedf0 !important;\r\n  cursor: not-allowed;\r\n}\r\n<\/pre>\n
    Field Definition<\/h2>\n
    To use our custom field, we need to define it on the module definition of our intended module. For this example, let\u2019s add it to the Simple Header module we created in the previous tutorial<\/a>. <\/p>\n
    Open the SimpleHeader.php<\/strong> file located at \/includes\/modules\/SimpleHeader\/SimpleHeader.php<\/code>. <\/p>\n
    Then add the code to define the custom field. Don\u2019t forget to use  simp_simple_input<\/code> as the field type.<\/p>\n
    \"custom<\/p>\n
    The final code will look like this:<\/p>\n
    \r\n\r\nclass SIMP_SimpleHeader extends ET_Builder_Module {\r\n\r\n\tpublic $slug       = 'simp_simple_header';\r\n\tpublic $vb_support = 'on';\r\n\r\n\tpublic function init() {\r\n\t\t$this->name = esc_html__( 'Simple Header', 'simp-simple-extension' );\r\n\t}\r\n\r\n\tpublic function get_fields() {\r\n\t\treturn array(\r\n\t\t\t'heading'     => array(\r\n\t\t\t\t'label'           => esc_html__( 'Heading', 'simp-simple-extension' ),\r\n\t\t\t\t'type'            => 'text',\r\n\t\t\t\t'option_category' => 'basic_option',\r\n\t\t\t\t'description'     => esc_html__( 'Input your desired heading here.', 'simp-simple-extension' ),\r\n\t\t\t\t'toggle_slug'     => 'main_content',\r\n\t\t\t),\r\n\t\t\t'content'     => array(\r\n\t\t\t\t'label'           => esc_html__( 'Content', 'simp-simple-extension' ),\r\n\t\t\t\t'type'            => 'tiny_mce',\r\n\t\t\t\t'option_category' => 'basic_option',\r\n\t\t\t\t'description'     => esc_html__( 'Content entered here will appear below the heading text.', 'simp-simple-extension' ),\r\n\t\t\t\t'toggle_slug'     => 'main_content',\r\n\t\t\t),\r\n\t\t\t'field'       => array(\r\n\t\t\t\t'label'           => esc_html__( 'Custom Field', 'simp-simple-extension' ),\r\n\t\t\t\t'type'            => 'simp_simple_input',\r\n\t\t\t\t'option_category' => 'basic_option',\r\n\t\t\t\t'description'     => esc_html__( 'Text entered here will appear inside the module.', 'simp-simple-extension' ),\r\n\t\t\t\t'toggle_slug'     => 'main_content',\r\n\t\t\t),\r\n\t\t);\r\n\t}\r\n\r\n\tpublic function render( $unprocessed_props, $content = null, $render_slug ) {\r\n\t\treturn sprintf(\r\n\t\t\t'<h1 class="simp-simple-header-heading">%1$s<\/h1>\r\n\t\t\t<div>%2$s<\/div>',\r\n\t\t\tesc_html( $this->props['heading'] ),\r\n\t\t\t$this->props['content']\r\n\t\t);\r\n\t}\r\n}\r\n\r\nnew SIMP_SimpleHeader;\r\n<\/pre>\n
    The properties that were added to the field are only the required properties you need to define. But you can add more properties to use on the custom field if you want. For instance, you can add both responsive and hover options for your custom field as well.<\/p>\n
    Divi Builder and Frontend Output<\/h2>\n
    Our field definition is ready. We just need to update the  render()<\/code> method so that it will display the custom field value. Let\u2019s start with the  render()<\/code> method on the module PHP class.<\/p>\n
    Open the SimpleHeader.php<\/code> file and update the render()<\/code> method as follows:<\/p>\n
    \"how<\/p>\n
    The final code should look like this:<\/p>\n
    \r\n\r\nclass SIMP_SimpleHeader extends ET_Builder_Module {\r\n\r\n\tpublic $slug       = 'simp_simple_header';\r\n\tpublic $vb_support = 'on';\r\n\r\n\tpublic function init() {\r\n\t\t$this->name = esc_html__( 'Simple Header', 'simp-simple-extension' );\r\n\t}\r\n\r\n\tpublic function get_fields() {\r\n\t\treturn array(\r\n\t\t\t'heading'     => array(\r\n\t\t\t\t'label'           => esc_html__( 'Heading', 'simp-simple-extension' ),\r\n\t\t\t\t'type'            => 'text',\r\n\t\t\t\t'option_category' => 'basic_option',\r\n\t\t\t\t'description'     => esc_html__( 'Input your desired heading here.', 'simp-simple-extension' ),\r\n\t\t\t\t'toggle_slug'     => 'main_content',\r\n\t\t\t),\r\n\t\t\t'content'     => array(\r\n\t\t\t\t'label'           => esc_html__( 'Content', 'simp-simple-extension' ),\r\n\t\t\t\t'type'            => 'tiny_mce',\r\n\t\t\t\t'option_category' => 'basic_option',\r\n\t\t\t\t'description'     => esc_html__( 'Content entered here will appear below the heading text.', 'simp-simple-extension' ),\r\n\t\t\t\t'toggle_slug'     => 'main_content',\r\n\t\t\t),\r\n\t\t\t'field'       => array(\r\n\t\t\t\t'label'           => esc_html__( 'Custom Field', 'simp-simple-extension' ),\r\n\t\t\t\t'type'            => 'simp_simple_input',\r\n\t\t\t\t'option_category' => 'basic_option',\r\n\t\t\t\t'description'     => esc_html__( 'Text entered here will appear inside the module.', 'simp-simple-extension' ),\r\n\t\t\t\t'toggle_slug'     => 'main_content',\r\n\t\t\t),\r\n\t\t);\r\n\t}\r\n\r\n\tpublic function render( $unprocessed_props, $content = null, $render_slug ) {\r\n\t\treturn sprintf(\r\n\t\t\t'<h1 class="simp-simple-header-heading">%1$s<\/h1>\r\n\t\t\t<div>%2$s<\/div>\r\n\t\t\t<p>%3$s<\/p>',\r\n\t\t\tesc_html( $this->props['heading'] ),\r\n\t\t\t$this->props['content'],\r\n\t\t\t$this->props['field']\r\n\t\t);\r\n\t}\r\n}\r\n\r\nnew SIMP_SimpleHeader;\r\n<\/pre>\n
    Now, let\u2019s edit the  render()<\/code> method of the React component and make it produce the same output that we defined in our PHP  render()<\/code> method.<\/p>\n
    Open the SimpleHeader.jsx<\/code> file and update the render()<\/code> method as follows:<\/p>\n
    \"how<\/p>\n
    The final code should look like this:<\/p>\n
    \r\n\/\/ External Dependencies\r\nimport React, { Component, Fragment } from 'react';\r\n\r\n\/\/ Internal Dependencies\r\nimport '.\/style.css';\r\n\r\n\r\nclass SimpleHeader extends Component {\r\n\r\n  static slug = 'simp_simple_header';\r\n\r\n  render() {\r\n    return (\r\n      <Fragment>\r\n        <h1 className="simp-simple-header-heading">{this.props.heading}<\/h1>\r\n        <div>\r\n          {this.props.content()}\r\n        <\/div>\r\n        <p>\r\n          {this.props.field}\r\n        <\/p>\r\n      <\/Fragment>\r\n    );\r\n  }\r\n}\r\n\r\nexport default SimpleHeader;\r\n<\/pre>\n
    Here you can see how the output of the render()<\/code> method of the php file corresponds to the output of the render()<\/code> method of the php file which now includes the new field wrapped in a p<\/code> tag.<\/p>\n
    \"how<\/p>\n
    Add Selectors if Needed<\/h3>\n
    Wrapping the new field output with a p<\/code> tag makes sense here because we are interested in simple text output. This also is a good opportunity to add your own custom selectors (CSS ID, CSS Class) to the p<\/code> tag for your own needs. Just make sure you add the same selectors to the output of the render()<\/code> method of the PHP file and the JSX file.<\/p>\n
    Testing Your Custom Fields<\/h2>\n
    If you already have yarn start<\/code> running as we suggested in the first step, you can now launch the Divi Builder and check out your Simple Input field!<\/p>\n
    If not, before we can test our custom field in the Divi Builder we need to compile the JSX code into regular JavaScript. To do that, simply run the following command inside your plugin\u2019s directory:<\/p>\n
    yarn start<\/pre>\n
    As a reminder, you should keep yarn start<\/code> running as you continue to edit your files so that the files continue to compile successfully.<\/p>\n
    To test out the custom field, go to your Divi site and open the settings of the custom Simple Header Module. The new Custom Field will be under the content tab.<\/p>\n
    \"custom<\/p>\n
    Wrapping up<\/h2>\n
    When you are finished development, remember to stop yarn start<\/code> from running in your terminal (hitting ctrl + c<\/strong> within the terminal usually does the trick). <\/p>\n