icon Form Builder
Created by Orckestra

Form Builder Developer Guide

How to create a new field type

Each field available in the Form Builder in the Component Library or Text & Decorations are Razor functions.

To create a custom field for the Form Builder, you need to:

  1. Create a Razor function that will render the filed on the form.
  2. Then register it in the Form Builder’s configuration file. See “The configuration file”.

Creating a custom field

To create a sample field:

  1. From the “Functions” perspective, add a new Razor function. Alternatively, you can create a Razor function in Visual Studio 2012. (Please see “Creating Razor Functions in Visual Studio”).
  2. Add necessary code and markup.
  3. Save the function.
  4. Now edit ~/App_Data/Composite/Configuration/Composite.Forms.FormBuilder.xml
  5. Add a field within one of the field groups, setting the attributes where needed and specifying the function created in Steps 1-3 for the field.
  6. Save the file.

Please see the following samples for illustration of a function’s code and markup and a field registration settings in Composite.Forms.FormBuilder.xml.

A simple field

The simplest example of the field is the existing Separator field that comes with the Form Builder.

@inherits RazorFunction
@using Composite.Forms.FormBuilder;
@functions {
   public override string FunctionDescription
   {
      get { return "A visual separator"; }
   }
}
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
</head>
<body>
   <hr />
</body>
</html>

Listing 1: Composite.Forms.FormBuilder.Fields.Decoration.Separator

As you can see in the code above, along with the regular Razor Function’s code (the inherit directive, description and the markup, the Razor function that stands for a field in the Form Builder should at minimum:

  • Include a using directive that references “Composite.Forms.FormBuilder”.

If the field has properties they should be declared as input parameters in this Razor function (see the following sample for illustration).

It is registered in the Form’s Builder’s configuration file like this:

<FormBuilder xmlns:f="http://www.composite.net/ns/function/1.0">
  <Fields>
    ...
    <FieldGroup label="${Composite.Forms.FormBuilder,FieldGroup.TextAndDecorations}">
     ...
     <Field name="decoration-separator" label="${Composite.Forms.FormBuilder,Fields.Decoration.Separator}" icon="icon-minus">
        <f:function name="Composite.Forms.FormBuilder.Fields.Decoration.Separator" />
      </Field>
     ...
    </FieldGroup>
  </Fields>
  ...
</FormBuilder>

Listing 2: The Separator registered in the configuration

In the configuration above, you can see that:

The field is declared with the Field element, which is place within a FieldGroup element (“Text and Decorations” in this example)

It uses the name attribute to be uniquely identified in the system.

It also uses the label and icon attributes to specify its corresponding elements in the Form Builder GUI.

The Field element nests the Razor function (here, Composite.Forms.FormBuilder.Fields.Decoration.Separator) that renders the field on a form.

The function may include no, one or more parameters.

A field with properties and validation

In the following sample, a text box is created, which only accepts numbers between 1 and 10 as the value. If the user enters anything else, a validation message is displayed.

The field comes with two properties: Label (used on the frontend) and Name (used programmatically).

 
@inherits RazorFunction
@using Composite.Forms.FormBuilder
@functions {
    [FunctionParameter(Label = Localization.Constants.Fields_Parameters_Name_Label, Help = Localization.Constants.Fields_Parameters_Name_Help)]
    public string Name { get; set; }
    [FunctionParameter(Label = Localization.Constants.Fields_Parameters_Label_Label, DefaultValue = null, Help = Localization.Constants.Fields_Parameters_Label_Help)]
    public string Label { get; set; }
}
@{
    string label = string.IsNullOrEmpty(Label) ? Name : Label;
    var formContext = FormHelper.GetFormContext();
    string value = "";
    if (formContext.IsFormSubmit)
    {
        value = Request.Unvalidated[Name];
        if (!string.IsNullOrEmpty(value))
        {
            int number;
            if (!int.TryParse(value, out number))
            {
                formContext.Errors.Raise(string.Format("Field '{0}' should contain an integer value.", value));
            }
            else if (number < 0 || number > 10)
            {
                formContext.Errors.Raise(string.Format("Field '{0}' should contain an value from [1, 10] range.", value));
            }
            else
            {
                formContext.Result.Add(Name, label, typeof(int), int.Parse(value));
            }
        }
    }
}
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
</head>
<body>
    <div class="form-group">
        <label for="form@(Name)" class="control-label">@label</label>
        <input type="number" class="form-control" id="form@(Name)"  name="@Name"  value="@value" min="1" max="10" />
    </div>
</body>
</html>

Listing 3: A custom field as a Razor function

In the example above, you can see that:

  • 2 properties are declared: “Label” and “Name”.
  • The label can be set explicitly via the Label property. Otherwise, it will be copied form the Name property’s value.
  • The validation logic for controlling the range of the numbers in the value is implemented that prevents users from entering invalid numbers or illegal characters.
  • Two HTML elements - <label/> and <input/> of the type “number” - are used to display the field on the form.
  • The field is nested within the <div> element of the class “form-group” and each HTML element has its own class applied to: “control-label” and “form-control”

This field should be registered in the Form Builder’s configuration file:

<FormBuilder xmlns:f="http://www.composite.net/ns/function/1.0">
  <Fields>
    <FieldGroup label="${Composite.Forms.FormBuilder,FieldGroup.Standard}">
     ...
      <Field name="onetoten" label="One To Ten" icon="icon-textbox">
        <f:function name="Composite.Forms.FormBuilder.Fields.OneToTen">
        </f:function>
      </Field>
     </FieldGroup>
  </Fields>
  ...
</FormBuilder>

Listing 4: A custom field registered in the configuration

 
Back to top
Version 1.3.4
Tags Form

Have a question?

Phone: +45 39 15 76 00
Email: Write us
7:31 PM
(Local time at HQ)