Walkthrough: Adding an embeddable form to a webpage

Current version: 10.3

With the Embeddable Forms Framework (EFF), you can render a Sitecore form on any webpage.

This walkthrough describes how to:

  • Prepare to work with EFF.

  • Add an embeddable form to a webpage.

  • Display a custom form element in an embeddable form.

Prepare to work with EFF

Before you can add an embeddable form to your web application, you must prepare your Sitecore instance and web application to work with the EFF.

To prepare your Sitecore instance and web application to work with the EFF:

  1. Install Sitecore Headless Services 21.0.0 zip package.

  2. Create an API key.

  3. Download and extract the Sitecore Embeddable Forms for Sitecore ZIP file, then copy the sitecore-embeddableforms.umd.js file to your web application directory.

  4. Copy the css folder to the root directory of your web application.

Add an embeddable form to a webpage

After you install Sitecore Headless Services, create an API key, and add the required files to your web application, you can add a Sitecore form to a webpage.

To add a form to a webpage:

  1. On the webpage where you want to display the form, add a script tag that refers to the EFF script:

    RequestResponse
    <script type="text/javascript" src="https://site.com/scmods/Web/eff/sitecore-embeddableforms.umd.js?sc_site=http://scsite.com&sc_apikey=626402f6-a864-4a2e-88cc-ca7b1edcd47b"></script>

    Parameter

    Description

    sc_apikey

    The API key for authentication to the Layout Service and the submission endpoint.

    sc_site

    Optional. The URL of the Sitecore website that is hosting the Layout Service and the submission endpoint. If you do not include this parameter, the EFF assumes that this script is hosted on a Sitecore instance that contains the Layout Service and the submission endpoint.

  2. Add a scef-form tag to specify the Sitecore form item:

    RequestResponse
    <scef-form formId="{BBB5CFC2-D2E0-426B-A78D-E8E151E0E9E0}"></scef-form>

    Attribute

    Description

    formId

    The ID of the Sitecore form item you want to add to the page.

The following is a sample HTML page that contains an embeddable form:

RequestResponse
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Sitecore Embeddable Forms Sample</title>
  </head>
  <body>
    <div class="my-page-container">
      <h1>Sitecore Embeddable Forms Sample</h1>
      <div class="my-embeddable-form-container">
        <scef-form formid="{BBB5CFC2-D2E0-426B-A78D-E8E151E0E9E0}"></scef-form>
      </div>
    </div>
    <script type="text/javascript" src="https://scsite.com/sitecore-embeddableforms.umd.js?sc_apikey=626402f6-a864-4a2e-88cc-ca7b1edcd47b"></script>
  </body>
</html>

Display a custom form element in an embeddable form

Note

You only have to follow this procedure if your form contains a custom form element.

If your Sitecore form contains a custom form element, you must create a class that renders the custom form element, then reference this class on the webpage that contains your embeddable form.

To display a custom form element in an embeddable form:

  1. Create a class that renders your custom form element.

    In the following example, the custom form element is based on the Single-Line text item in the /sitecore/system/Settings/Forms/Field Types/Basic folder.

    RequestResponse
    import { css, html } from 'https://unpkg.com/lit@^2?module';
    import { ifDefined } from 'https://unpkg.com/lit@^2/directives/if-defined.js?module';
    export class ScefCustomLineText {
      id = "YOUR-CUSTOM-FORM-ELEMENT-ITEM-ID-WITHOUT-BRACKETS";
      render(
        field,
        themeElement,
        placeholderText,
        errorMessage
      ) {
        return html`
          <div part="form-control">
            <label
              part="label"
              for=${field.valueField.id}
              class="${themeElement.GetCssClass(this, "common.text.label")}"
            >
              ${field.title} Load Custom Label scef-customlinetext
            </label>
            <div
              part="base"
              class="${themeElement.GetCssClass(this, "common.text.div")}"
            >
              <input
                part="input"
                type="text"
                id=${field.valueField.id}
                name=${field.valueField.name}
                class=${themeElement.GetCssClass(this, "common.text.input")}
                maxlength=${ifDefined(
                  field.maxLength > 0 ? field.maxLength : undefined
                )}
                placeholder=${ifDefined(placeholderText)}
                data-sc-tracking=${field.isTrackingEnabled}
                data-sc-field-name=${field.name}
                data-sc-field-key=${field.fieldKey}
                ?disabled=${field.disabled}
                .value=${field.value}
                @input="${field.validate}"
              />
            </div>
            <div ?hidden=${!errorMessage}>
              <p
                id="scef-errorcontent"
                name="${field.valueField.name}.scef-errorcontent"
                for=${field.name}
              >
                ${errorMessage}
              </p>
            </div>
          </div>
          <link rel="stylesheet" href="${themeElement.GetCssURL()}" />
        `;
      }
    }
  2. On the webpage that contains your embeddable form, add a script tag that refers to your class.

    RequestResponse
        <script
        type="module"
        useOn="customfield"
        guid="B02DAEA0-79A3-4E9D-B468-2E4FE6DAE4ED"
        ctor="ScefCustomLineText"
        renderMode="render"
        src="http://website.com/scef-customlinetext.js"
      ></script>

    Attribute

    Description

    useOn

    Indicates to the EFF how to process the script. customfield is the only available value.

    guid

    The ID of the custom form element item.

    ctor

    The class that renders the custom form element.

    renderMode

    The method that renders the custom form element.

    src

    The URL of the class that renders the custom form element.

The following is a sample HTML page that contains an embeddable form with a custom form element:

RequestResponse
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Sitecore Embeddable Forms Sample</title>
  </head>
  <body>
    <div class="my-page-container">
      <h1>Sitecore Embeddable Forms Sample</h1>
      <div class="my-embeddable-form-container">
        <scef-form formid="{C8D49EE3-6BD8-4607-AF88-9E534EFCCF3A}"></scef-form>
      </div>
    </div>
  </body>
  <script type="text/javascript" src="http://website.com/sitecore-embeddableforms.umd.js?sc_site=https://scsite.com/&sc_apikey=7A769112-5897-4429-9672-4AD8A8947D82"></script>  
  <script
    type="module"
    useOn="customfield"
    guid="B02DAEA0-79A3-4E9D-B468-2E4FE6DAE4ED"
    ctor="ScefCustomLineText"
    renderMode="render"
    src="http://website.com/scef-customlinetext.js"
  ></script>
  </html>

Do you have some feedback for us?

If you have suggestions for improving this article,