Documentation › Plumsail Public Forms Provisioning API: Create and update forms programmatically

Plumsail Public Forms Provisioning API: Create and update forms programmatically

You can create Plumsail public forms from scratch and provision them programmatically using the API available via the Plumsail.Forms.Public NuGet package. This package also lets you edit and delete existing forms.

In order to use the package, your project must be compatible with .NET Standard 2.0.

Note

Check out Create a contact web form in Visual Studio example to see this API used in practice.

API client

FormsClient lets you connect to your account and start working with its forms. There are several ways to initialize a client object:

Constructor

Description/Examples

FormsClient(string apiKey);

Use your API key to authenticate. Forms API keys are managed on the API keys page.

apiKey - your API key secret


Example:

var client = new FormsClient("<your-api-key>");

FormsClient(string login, string password);

Use your Plumsail account credentials to authenticate.

login - your Plumsail Account login

password - your Plumsail Account password


Example:

var client = new FormsClient("login", "password");

FormsClient(HttpClient httpClient);

Initialize FormsClient using HttpClient.

httpClient - HttpClient that you can configure beforehand


Example:

using System.Net.Http;
using System.Net.Http.Headers;

var httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<token>");
var client = new FormsClient(httpClient);

Use the following FormsClient methods to manage your forms:

Method

Description/Examples

NewForm(string name)

Create a new public web form with the specified name

name - name of the form


Example:

var form = client.NewForm("Form name");

GetForms()

Async method to get all forms from the account


Example:

// get forms list
var forms = await client.GetForms();

GetForm(string formId)

Async method to get a specific form from the account

formId - ID of the form


Example:

// get forms list
var forms = await client.GetForms();
// get the ID of the first form
var formId = forms.First().Id;
// get the form from the account by its ID
var form = await client.GetForm(formId);

DeleteForm(string formId)

Async method to delete a specific form from the account

formId - ID of the form


Example:

var forms = await client.GetForms();
var form = forms.First();
await client.DeleteForm(form.Id);

GetTeams()

Async method to get teams from the account. Each team has Name and OwnerId properties.

Note

This method is not supported for clients authenticated with API key.

Example:

var teams = await client.GetTeams();
foreach (var team in teams)
{
    Console.WriteLine(team.Name);
    Console.WriteLine(team.OwnerId);
}

SetTeam(string ownerId)

Async method to set the team for the client. Future requests will be done for the team forms.

OwnerId - ID of the team (GUID)

Note

This method is not supported for clients authenticated with API key.

Example:

await client.SetTeam("--- ID of the team ---");

Form API

Use NewForm(string name) or GetForm(string formId) to start working with a form.

Method/Property

Description/Examples

SavePosts

Get or set this boolean property that determines whether form submissions are saved to your Plumsail Account.


Example:

form.SavePosts = true;

Notification

Get or set this property that determines whether form submissions are sent as messages to owner / team email addresses. Use NotificationRecipient enum to set the value.


Example:

// send notifications to owner
form.Notification = NotificationRecipient.Owner;

// send notifications to team
form.Notification = NotificationRecipient.Team;

// do not send email notifications
form.Notification = NotificationRecipient.None;

Enabled

Get or set this boolean property that determines whether form submissions are sent to the server.


Example:

form.Enabled  = true;

Save()

Async method to save the form layout and settings.


Example:

try
{
    await form.Save();
}
catch(InvalidLoginException)
{
    // Set correct authorization header
}
catch(BadRequestException ex)
{
    // ex.Message
}

Layout API

Layout is the main content of the form. It’s the property that holds PC/Tablet/Phone layout data, as well as JavaScript, CSS, and the theme data of each form.

Method/Property

Description/Examples

Css

Get or set CSS code for the form.


Example:

form.Layout.Css = ".fd-form h1 { color: red }";

JavaScript

Get or set JavaScript code for the form.


Example:

form.Layout.JavaScript = "fd.rendered(() => { fd.field('Name').value = 'John Bull' });";

Theme

Get or set theme used for the form. Use one of predefined themes such as Blue, Compact, Default, Explicit, Gray, Green, Orange, Plumsail, Purple, Red, Smooth, or Soft.


Example:

form.Layout.Theme = new Theme(PredefinedThemes.Compact);

PC/Tablet/Phone

Get or set grid that will nest the rest of the form. At least one of these must be filled before the form is saved.

When creating a grid, make sure that each row’s width is less or equal to 12.


Example:

form.Layout.PC = new Grid(
    new GridRow(
        new GridCell(new Text("Text1")
        {
            // configure control
            Content = "This is form, created with using Designer.Public",
            Class = "text-control-class",
            Style = "border: 1px solid red;"
        }, width: 6)
        { Offset = 2, Class = "grid-cell-class" }, // configure cell
        new GridCell(new Submit("Submit1")
        {
            Width = 300
        }, width: 4)
    )
);

Fields and controls API

These can be placed inside of cells, and configured using their own properties.

Constructor

Description/Examples

new Field/Control(string name)

Create fields or controls by giving them name and setting their properties.

name - name of the field/control


Example:

new GridRow(
    new GridCell(new SingleLineTextField("Name")
    {
        Title = new FieldTitle() { Text = "Name" },
        ControlHint = "David Bowie",
        Orientation = Orientation.Vertical
    }, width: 6),
    new GridCell(new DateField("Date")
    {
        Title = new FieldTitle() { Text = "Date" },
        ControlHint = "Today's date",
        Required = true,
        Orientation = Orientation.Vertical
    }, width: 6)
),
new GridRow(
    new GridCell(new DropDownField("Country")
    {
        Title = new FieldTitle() { Text = "Country" },
        Required = true,
        Orientation = Orientation.Vertical,
        Options = new[]
        {
            new ChoiceOption("USA", "blue", "#ffffff"),
            new ChoiceOption("Canada", "red", "#ffffff"),
            new ChoiceOption("Mexico", "green", "#ffffff")
        }
    }, width: 6),
    new GridCell(new Submit("SubmitButton")
    {
        Width = 300
    }, width: 6)
)