Sitecore Forms Extensions 1.8 for Sitecore 9.0.x¶

Click here to read the documentation on Sitecore Forms Extensions 2.1 for Sitecore 9.1.

Welcome, happy to see your are (considering) using the Sitecore Forms Extensions module to give your Sitecore 9 forms a feature boost!

With this module you will be able to prefill forms, get a file upload field, get better integration with EXM, a Google Recaptcha, additional validators and much more.

These pages serve as the documentation for the module. They are splitted into 2 sections:

Content Editor Documentation Here you will find how to use the module once installed and configured.
Developer Documentation This part contains installation instructions and info on how to add customizations on the module that fit your solution.

If you are missing stuff in this documentation. Feel free to send me a private message on Sitecore Slack (@bverdonck) or send me a tweet on twitter (@_onelittlespark).

Found a bug? Please reported it on Github

Have fun with the module!

Custom Fields¶

The Sitecore Forms Extensions module provides a number of additional fields to use on your forms.

Recaptcha¶

To use the recaptcha component, just drag it onto your form. There are no configurations to be made.

File Upload¶

Allow your users to upload files through your form by using the File Upload field.

To use the component drag it onto the form.

Set the allowed files¶

Optionally, if you which to restrict the file upload to certain file types, you can enable the ContentType Validator.

When enabled, you need to fill in the Allowed Content Types field and add the content types you which to allow. Add multiple content types on seperate rows.

Limit file size¶

Optionally, you can limit the size of the files that are allowed to upload.

With the file size validator you can limit the maximum allowed file size of the uploads. The value is in bytes and is validated client and server side.

Raw HTML¶

With the Raw HTML component you can add unescaped content onto your form. This allows to add small custom javascripts or some custom tailered html snippets on your form.

Draw the Raw HTML component on the form. Select the component and add html in the HTML field.

Hidden Field¶

The hidden fields renders an <input type=”hidden” value=”” /> in your form.

This can be usefull when you want to send additional data to the client browser to be processed by some javascript.

An example of this could be to send additional data on the google datalayer.

To use, drag the component on the form.

Give the field a name, and select a prefill binding to fill in the value of the field.

More info no prefilling can be found on Form Bindings (Prefilling)

Send Mail¶

With the “Send Email” submit action, a mail can be send out after the submittion of the form.

The action works in collaboration with Email Experience Manager (EXM), the build in email client of Sitecore.

To use the “Send Email” action, you should first create an automated messsage in the EXM module.

Create an automated message in Email Experience Manager¶

The “Send Email” submit action works in collaboration with Email Experience Manager (EXM).

Learn here, how to setup an email to be used for the send mail action.

Creating a new automated campaign¶

First, go to Email Experience Manager and create a new automated message.

_images/SFE-EmailFixed-ExmCreateCampaign.png

Take any of the available templates. In the best case, some custom tailored templates are provided by the developers for your site.

_images/SFE-EmailFixed-ExmChooseTemplate.png

Fill in the general info like “from” name and email.

_images/SFE-EmailFixed-ExmGeneralInfo.png

Use the template to fill in the body of your email message.

Finally, we need to activate the message in the delivery tab. Only activated message will be available to use on the “Send Mail” action.

Using form values in the email¶

To print the form data entered by the visitor in the email, you must use tokens. These tokens will be replaced with the actual values when someone submits the form and an email gets send out.

The form fields can be referenced individual, field per field, or you can use one token that will print all values from the form in one token.

Using individual tokens¶

In the forms module, each field you add should be given a name.

Use this name to contruct the token.

Token format:

$form_fieldname$ where fieldname should be replaced by the name of the field.

So in this case this would be $form_firstName$

Print all field values with one token¶

Use the token $formFields$ to print all fields with their value in the email.

How to use the Send Mail action¶

Create a basic form with Sitecore Forms make sure to add a submit button.

On the submit button, go to submit actions and add the send email to fixed address action.

Now, we need to pick the automated message created in EXM. This message will be send upon submittion of the form.

Next, we need to choose who will be the recipients of the mail.

Send to current contact¶

Pick mailto “current xDB contact’s email address”.

Just like the sitecore build in ‘send email campaign message’ submit action, this will send the exm mail to the current identified contact.

However, using the send email action from the Sitecore Forms Extensions module will make the forms field values available as tokens for the composed email.

Note that, when you use the action, you must make sure that the current visitor is identified and has an email address on his contact data. In order to this, you could use the Form Bindings (Prefilling) feature on an email field in the form.

_images/form-12-dialog-currentcontact.png

Send to fixed email address¶

Choose mailto “Fixed Email Address”

This options is most usefull when you want to email the backoffice after a form was submitted.

Fill in the email addresses the mail needs to be send to.

You can specify multiple addresses by using a semicolon between the addresses. Make sure to leave no spaces.

Send to form field value¶

Use this option to email the visitor that has filled in the form.

Choose mailto “Value from field in form”

Choose one of the fields of the form. This field must contain an email address. It can be a free email field for the visitor to enter it’s email address or it could also be a dropdown with choices that have an email as value. (For example if you want to mail to a different department based on a chosen topic).

With this option you can also check the “update current contact” checkbox.

When you check this box, then upon submittion, the current session will be updated with the value from the chosen field. This session will then become identified instead of anonymous. (If the session was already identified, the email will just be updated in the profile.

When this box is not checked, we will lookup if there is a contact with the provided email address. If we find a contact, we will use this contact, if not, a new contact will be created.

Attachments¶

When using File Upload fields in your form, you can choose to add them as an attachment of the email.

Form Bindings (Prefilling)¶

With the form bindings, you an prefill fields in your form based on xDB contact data. The form bindings also support to store the data entered in the form on your xDB contact.

Note: For security reasons it might be prudent to limit prefilling to forms behind a login. Storing info on the profile is less sensitive and can be used on forms without login. More info on https://www.campaignion.org/blog/all-you-have-know-about-pre-filling-forms

How to configure a field¶

In the forms editor, select the field you wish to prefill.

Check the “Bindings” section in the panel on the right.

Source¶

Mandatory

In the source field, you must select what source you want to link the field to. The prefill value of the form will be fetched form this source.

Prefill Value¶

Optional

Check the “prefill value” checkbox in order to prefill this field with the selected source.

Store Value¶

Optional

Check the “store value” checkbox in order to save the value entered by the visitor in the form to the selected source.

Supported Form Elements¶

This functionality is available for form elements of the type:

Single-Line Text
Multi-line Text
Number
Email
Hidden
Telephone
Checkbox
Date

Example¶

Build Form¶

Let’s create a new form with 3 fields:

FirstName: We will prefill this from the xDB profile and store it back upon form submition

Email: We will prefill this from the xDB profile and store it back upon form submition

Birthday: We will only store the value, but not prefill it

Finally we will add a submit button with no submit actions attached. (just for the example, it is perfectly possible to add submit actions)

Finish by putting the form on a page and test it.

Testing¶

Let’s visit the form now.

Considering a new first time visitor, the form will be empty, since there is no data on his xDB profile yet.

The visitor fills in the form and submit’s. The data entered will now be stored in the selected xDB fields.

The visitors revisits the form (or any other form configured with data binding), the fields first name and email will be prefilled with the data form the xDB profile.

Value Provider Conditions¶

When a visitor browses to your site, we might already have a lot of information on him based on his xDB tracking cookie. When prefilling of forms is enabled by use of the fieldbindings, we can prefill the form fields from xDB. This might not always be the desired behaviour, there may be cases where you only want to prefill when a user is logged in, or has given concent to prefill the form.

With the Value Provider Conditions, you can build rules that must be met, before prefilling is applied.

How to create a set of rules¶

In the content explorer, navigate to /sitecore/system/Settings/Forms/Value Provider Conditions

Create a new ValueProviderConditions item.

_images/create-valueproviderconditions-1.png

Next, click on “Edit Rule” and build the conditional rule you desire.

_images/create-valueproviderconditions-2.png

Save and publish the rule.

How to use a set of rules¶

In the content explorer, navigate to your form. (Sitecore –> Forms –> Your Form)

In the Value Provider section, choose your conditions.

_images/apply-valueproviderconditions.png

Save and publish the form.

In place “Thank you” message¶

The ShowFormPage custom submit action makes it possible to show a thank you message after submitting the form without the need of creating a dedicated seperate thank you page.

With this action, the form is replaced inline via ajax, there is no other page loaded.

How¶

Let’s create a simple form to let users subscribe to a kind of newsletter.

The form contains a single email field and a submit button, with the submit action save data.

Now, let’s add a second page in the form (just like you would do for a multipage form).

Give the page a name.

Add some components on the thankyoupage.

On the submit button: add the submit action “show form page” and select the thank you page.

Result¶

After submit:

Installation and Setup¶

Download¶

The latest version can be found in the download section on Github.

There are 3 distribution packages available:

Sitecore Forms Extensions-<version>.zip: Sitecore Package to install via Sitecore’s installation wizard. This is the most common option.
Sitecore Forms Extensions-<version>.scwpd.zip: Use this package for initial install on Azure PaaS via ARM templates.
Sitecore Forms Extensions-<version>-nodb.scwpd.zip: Use this package for redeployment via ARM on Azure PaaS, this package will only install DLL’s and file, sitecore items are excluded from this package.

Install¶

Just install the package in Sitecore via installation wizard.

Configuration¶

Most functionalities of the libray work out of the box. However, the fileupload and captcha features require some additional configuration.

File Upload¶

The file upload requires to set a location to store the uploaded files. A file upload storage provider must be added in configuration.

There are currently 2 store locations available:

Configure Azure Blob Storage¶

Setup Storage Account in Azure¶

First, in the case you don’t have an Azure Blob Storage in your solution already, you will need to create one.

To do so, go into azure portal. Click New and choose Storage Account.

Next, create a storage container.

Choose public access level blob if you want easy access to the uploaded files by link. (All files will be renamed with a random GUID for security.)

Note: This is not required for the module to work

Add config file to your solution¶

Next, we will tell the module how to connect to the storage account.

Create a file Feature.FormsExtentions.AzureStorageProvider.config and add it in your website folder under App_Config/Environment

<?xml version="1.0"?>
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/"  xmlns:role="http://www.sitecore.net/xmlconfig/role/">
  <sitecore>
    <formExtensions>
      <fileUploadStorageProvider type="Feature.FormsExtensions.Business.FileUpload.AzureBlobStorageFileUploadStorageProvider, Feature.FormsExtensions">
        <connectionString></connectionString>
        <blobContainer></blobContainer>
        <folder>formextentions/{formName}/{fieldName}/{language}</folder>
      </fileUploadStorageProvider>
    </formExtensions>
  </sitecore>
</configuration>

Go to your storage account on Azure, browse to Access Keys, and copy either one of the connectionstrings. Put this connectionstring in the config.

Enter the name you have chosen for your container in the blobcontainer part of the configuration.

Finally, you will notice the folder attribute in the configuration. You can leave this empty or put in any desired folder structure that should be followed to store your files in.

All forms will follow the same config for upload of the files. You cannot create individual storages for individual forms. This is a design choice, so that content editors do not have to wory about where to store files.

However, the folder structure does support 3 variables that can be used:

{formName} This handle will get replaced by the name of the form.
{fieldName} Each form-upload field can be named in the forms-editor. This handle will be replaced by that name.
{language} If you want to seperate the content by language, use this handle.

Note that none of these handles are required. They are all optional, including the order.

Local Blob Storage¶

Please note that when using this configuration on a loadbalanced CD, you must make sure, the local filepath is shared between the instances.

Add config file to your solution¶

Create a file Feature.FormsExtentions.LocalStorageProvider.config and add it in your website folder under App_Config/Environment

<?xml version="1.0"?>
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/"  xmlns:role="http://www.sitecore.net/xmlconfig/role/">
  <sitecore>
    <formExtensions>
      <fileUploadStorageProvider type="Feature.FormsExtensions.Business.FileUpload.FileSystemFileUploadStorageProvider, Feature.FormsExtensions">
        <rootStoragePath>c:\temp\</rootStoragePath>
        <fileDownloadUrlBase>https://myfile.com/{0}</fileDownloadUrlBase>
                <folder>formextentions/{formName}/{fieldName}/{language}</folder>
      </fileUploadStorageProvider>
    </formExtensions>
  </sitecore>
</configuration>

The fileDownloadUrlBase is use to build a url that will host the uploaded images. Note that the module won’t serve the images. It is up to you to provide a download service for the images. If you don’t want to create this, consider using Azure Blob Storage Provider. It is not mandatory that a download service is provided for the module to work.

Make sure the application has enough rights to create files in the rootStoragePath you configured.

All forms will follow the same config for upload of the files. You cannot create individual storages for individual forms. This is a design choice, so that content editors do not have to wory about where to store files.

However, the folder structure does support 3 variables that can be used:

{formName} This handle will get replaced by the name of the form.
{fieldName} Each form-upload field can be named in the forms-editor. This handle will be replaced by that name.
{language} If you want to seperate the content by language, use this handle.

Note that none of these handles are required. They are all optional, including the order.

Google Captcha¶

For Google Captcha to work, we need to set the public and private key in the configuration.

Configure Google Captcha v2¶

Setup Google Account¶

First we need to configure our account in Google Recaptcha Portal.

https://www.google.com/recaptcha/admin#list

Add Config File to your Solution¶

Create a file Feature.FormsExtentions.GoogleRecaptcha.config and add it in your website folder under App_Config/Environment

<?xml version="1.0"?>
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/"  xmlns:role="http://www.sitecore.net/xmlconfig/role/">
  <sitecore role:require="Standalone or ContentManagement or DedicatedDispatch">
    <settings>
      <setting name="GoogleCaptchaPublicKey" value="6Lfik1cUAAAAAO3osc-yX6ZfZhckPm_4GIAKGdkh" />
      <setting name="GoogleCaptchaPrivateKey" value="6Lfik1cUAAAAAInwnC6-jlgbcGeZGp701AOXaSHL" />
    </settings>
  </sitecore>
</configuration>

The setting “GoogleCaptchaPublicKey” should contain the site key.

The setting “GoogleCaptchaPrivateKey” should contain the secret key.

Custom Bindings¶

Extend the Form Bindings (Prefilling) with your own custom xDB facets or even with an entirely different source like an ERP system.

Add a custom binding source¶

Create BindingHandler¶

To add a custom binding source, you should write a IBindingHandler interface.

namespace Feature.FormsExtensions.Business.FieldBindings
{
  public interface IBindingHandler
  {
    IBindingHandlerResult GetBindingValue();
    void StoreBindingValue(object newValue);
  }
}

The GetBindingValue should return a IBindingHandlerResult.

An example implementation could be like:

namespace Feature.FormsExtensions.Business.FieldBindings
{
  public class DemoBindingHandler : IBindingHandler
  {
      public IBindingHandlerResult GetBindingValue()
      {
          var fullName = Sitecore.Context.User.Profile.FullName;
          if (string.IsNullOrEmpty(fullName))
          {
              return new NoBindingValueFoundResult();
          }
          return new BindingValueFoundResult(fullName);
      }

      public void StoreBindingValue(object newValue)
      {
          if (newValue is string fullName)
          {
              Sitecore.Context.User.Profile.FullName = fullName;
          }
      }
  }
}

The storebindingvalue is only called when the newValue is not null.

Register BindingHandler¶

To register the bindinghandler(s) you have created, you must create a processor.

public class DemoBindingHandlerLoader : MvcPipelineProcessor<LoadFieldBindingHandlersArgs>
{
  public override void Process(LoadFieldBindingHandlersArgs args)
  {
    var tokenKey = new FieldBindingTokenKey("My Custom Handlers","x.y.z.customhandler","Custom Handler");
    args.FieldBindingHandlers.Add(tokenKey,new DemoBindingHandler());
  }
}

The tokenkey consists of 3 parameters:

Category: this will group the handlers in the sitecore forms user interface
Id: a unique id for your handler (this can be anything)
Name: the name of the handler that will be shown to the user

Once forms are created with your custom handler, you should not change the id anymore. The category and name can be safely changed as they are not stored on the form components.

Add the BindingHandlerLoader to the loader pipeline¶

Create a config file to add your loader to the forms.loadFieldBindingHandlers pipeline.

<configuration>
  <sitecore>
    <pipelines>
      <forms.loadFieldBindingHandlers>
        <processor type="mypackage.DemoBindingHandlerLoader , mydll" resolve="true" />
      </forms.loadFieldBindingHandlers>
    </pipelines>
  </sitecore>
</configuration>

Configure preferred email, address and phonenumber¶

The module comes with a set of databinding handlers to support xDB. The email, address and phonenumber facet on the contact profile contain a lists. There is always one preferred entry in the list.

The build in bindings always store and load from the preferred email, address or phonenumber.

If the facet does not yet exist, it has to create the facet and set the preferred email, address or phonenumber. The key that is used for this is stored in a sitecore setting. These settings can be overridden to fit your projects needs.

<?xml version="1.0"?>
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/"  xmlns:role="http://www.sitecore.net/xmlconfig/role/">
  <sitecore>
    <settings>
      <setting name="XDbPreferredAddress" value="address" />
      <setting name="XDbPreferredPhoneNumber" value="phone" />
      <setting name="XDbPreferredEmailAddress" value="email" />
    </settings>
  </sitecore>
</configuration>

Configure Date Timespan Validator¶

The Date Timespan Validator is a new custom validator released in version 1.5 of the Sitecore Forms Extensions module.

The module comes with 3 preconfigured timespan validators, but you can easily add you own.

The validators are defined in /sitecore/system/settings/forms/validations/formsextensions.

We provide a future date, past date and minimum age 18 validator with the package. Feel free to add you own timerange validator.

The validators are added on the date field located at /sitecore/system/settings/forms/field types/basic/date

Once configured, the validators become available in the forms editor on a date field.