• Use AB_GeneralForm to implement forms on CMS website pages

Use AB_GeneralForm to implement forms on CMS website pages

  • 915 Views
  • Last Post 09 March 2017
dwebb posted this 28 June 2016

Accelerator 6.4.0 introduces a new CMS feature: AB_GeneralForm. This feature allows simple forms to be added to CMS website pages with a div tag and data attributes, similar to the way Bootstrap Javascript plugins work. Some form types are available in Accelerator and others can be added by the website project; the form type defines a set of available fields and their validation rules using standard DataAnnotations property attributes. The CMS page markup decares which fields to use, their order, and whether or not they are required. It also declares actions to take when the form is submitted: send an email to the user, send an internal email, create a workflow instance, redirect to a different CMS page, unhide an element on the page and insert a message into it.

In the CMS page:

<div data-a4dn-general-form="contact-info"
    data-a4dn-fields="*FirstName,*LastName,*Email,Company,Title,Phone,Address,*Message"
    data-a4dn-display-template="bs-form-icons"
    data-a4dn-requestor-mandrill-template="..."
    data-a4dn-internal-mandrill-template="..."
    data-a4dn-workflow-namespace="..."
    data-a4dn-confirmation-modulenumber="..."
    data-a4dn-show-on-success="..."
    data-a4dn-show-on-error="..."
    data-a4dn-submit-label="..."
></div>

This element's content will be populated with the "contact-info" form, rendered using ~/Views/AB_GeneralForm/bs-form-icons.cshtml, and only showing the fields listed in data-a4dn-fields. Any field names prefixed with * will be required. If submit-label is provided, it will override the label on the Submit button.

NOTE: Currently, a CMS page can only contain one element like this at a time. Support for multiple forms on a page is planned for a later release.

  • a4dn-general-form: The value "contact-info" gets mapped to the C# model class that has properties for all of the available fields for this form type. Website projects can define their own types and add them to the mapping list.
  • a4dn-fields: A comma-separated list of the fields to show, prefixed by * if they are requried. The field names match the C# property names, Mandrill merge tag names, and Workflow custom field namespaces.
  • a4dn-display-template: The name of the Razor template used to render the model. This allows different form styles to be used with the same model / form type. Website projects can provide their own templates.
  • a4dn-requestor-mandrill-template: Optional. If provided the form data will be emailed to the user using the specified Mandrill template. The model class must specify which form field to use for the user's email address and name; therefore not all form types support emailing the user.
  • a4dn-internal-mandrill-template: Optional. If provided the form data will be emailed to a configured email address using the specified Mandrill template. The website project's web.config file must contain an AB_GeneralForm.InternalEmail setting.
  • a4dn-workflow-namespace: Optional. If specified a new Workflow Instance will be created for the given workflow. The model class can populate the instance name with any of the form fields.
  • a4dn-confirmation-modulenumber: Optional. If specified a successful form submission will cause the browser to load the CMS page for the given module number.
  • a4dn-show-on-success: Optional. If specified the value should be a selector expression for a hidden element to show after successfully submitting the form. If the element contains an element with class a4dn-js-message, it's content will be set to the success message returned by the server.
  • a4dn-show-on-error: Optional. If specified this works like show-on-success, except for non-validation error messages when the form submission fails. (Eg: failure to send an email.)
  • a4dn-submit-label: Optional. The label for the submit button; defaults to Submit (or whatever the display template chooses to use.)
  • a4dn-{fieldname}: Optional. To override the label and placeholder text for a field, add a data attribute named a4dn- and the fieldname in lowercase. (Don't include the * for required fields.) The value of the attribute should be the label, a | character, and the placeholder text.
  • a4dn-{fieldname}-options: Optional. Specifies allowed values for the field, which will be rendered as a dropdown select control. The attribute value can be either a comma-separated list or the id or name of a Property Code table.

confirmation-modulenumber cannot be used with show-on-success; use one or the other.

If show-on-error is not specified, or if it is specified but the element selector does not locate an element, then errors will be displayed in a Javascript Alert popup dialog.

If confirmation-modulenumber is not specified, and show-on-success is either not specified or the selector doesn't locate an element, then the success message returned  by the server will be shown in a Javascript Alert popup dialog.

mvc cms
Order By: Standard | Newest | Votes
dwebb posted this 28 June 2016

Error/Success element example:

<div class="hidden alert alert-success" id="Success">
    Your request has been received!
</div>
<div class="hidden alert alert-danger" id="Error">
    <strong>An error occurred:</strong><br />
    <span class="a4dn-js-message"></span>
</div>

<div ...
    data-a4dn-show-on-success="#Success"
    data-a4dn-show-on-error="#Error"
></div>

These two alert elements will be shown/hidden based on the type of result after the form is submitted. The browser window will also be scrolled to bring the alert element near to the center of the window.

Note that the #Success alert does not contain a4dn-js-message. The CMS page is providing its own success message, ignoring the message returned by the server. This is often the recommended approach for success messages, but error alerts should always use a4dn-js-message so the specific error message can be displayed.

dwebb posted this 28 June 2016

In the Website Project

The website project must initialize the AB_GeneralForm javascript plugin and include any display templates that will be used.

To initialize the plugin, add the following to _Layout.cshtml:

@{
    var formUrl = Url.Action("Form", "AB_GeneralForm");
}
<script src="~/Content/js/a4dn.ab_generalform.js"></script>
<script>
    $(function() {
        $('body').AB_GeneralForm({ formUrl: '@formUrl' });
    });
</script>

This will find the element(s) with the data-a4dn-general-form attribute and call formUrl to load the form markup, set up client-side validation, and attach a submit handler that posts the form with an ajax request. The post will go to the action specified in the form markup; typically /AB_GeneralForm/Submit.

The website project must include a copy of a4dn.ab_generalform.js, and also Razor templates in ~/Views/AB_GeneralForm such as bs-form-icons.cshtml. (These files can be found in the Accelerator source code.) The model class for the contact-info for type is A4DN.Core.MVC.CMS.Models.AB_GF_ContactInfoModel.

If sending emails to users, also remember to define a web.config setting for AB_GeneralForm.InternalEmail.

dwebb posted this 28 June 2016

Adding New Form Types

To add a new form type, the website project must define a new model class which inherits from AB_GeneralFormModel. It is also possible to inherit from a child of AB_GeneralFormModel, such as AB_GF_ContactInfoModel, to override validation attributes on an existing property or to add additional properties.

To send an email to the user, the model class must override ap_UserEmailAddressap_UserEmailName to return the user's full name.

If form submissions will be added to a Workflow, the model class must override ap_InstanceName to provide text to use as the name of the new Workflow instance. (This is the text that appears in the Workflow Instance search results grid.)

During startup, a new entry should be added to AB_GeneralFormController.ap_GeneralFormModelTypes, which is a static dictionary. The key is the new form type name which will be used for data-a4dn-general-form, and the value is the Type of the new model class.

Finally, at least one Razor display template must be defined which is used to render the form for the new model type. The template's model will be an instance of the model class, and ViewBag.Metadata will contain an AB_GeneralFormModelMetadata object that contains most of the data- attributes from the CMS markup. The template should use metadata.ap_FieldNames and metadata.am_IsFieldRequired(fieldName) to determine which fields to render and whether or not to make them required. The template should also use metadata.SubmitLabel for the submit button if it is not empty. See bs-form-icons.cshtml for guidance.

dwebb posted this 30 September 2016

Example: "contact-info" form type and bs-form-icons template

Fields available: Field Name, label, and placeholder

  • FirstName: "First Name", "Your First/Given Name"
  • LastName: "Last Name", "Your Last/Family Name"
  • FullName: "Full Name", "Your Full Name"
  • Email: "Email", "Your Best Email"
  • Phone: "Phone", "Your Best Phone Number"
  • Company: "Company", "Your Company Name"
  • Title: "Job Title", "Your Position/Job Title at the Company"
  • Address: "Address", "Your Full Address including Country if outside the U.S."
  • Message: "Message", "Tell us more about your interests"

Address and Message are multi-line inputs; the rest are single-line text boxes

dwebb posted this 09 March 2017

Using SMTP instead of Mandrill (Added in Accelerator 7.2.0.0)

An SMTP server can be used instead of Mandrill for the requestor template, the internal template, or both. You can mix and match services as-needed; all four settings are independently controlled.

To use SMTP, additional data- attributes are needed:

  • a4dn-requestor-smtp-view: The name of a Static Web Content page in your website's Website Pages. If you use just the name, put the page under /Views/Shared/. If you put it anyplace else, specify the full path starting with /Navigation/. Eg: "/Navigation/Views/EmailTemplates/contact-us-template"
  • a4dn-requestor-sender-address: The email address that should be used for the From: line.
  • a4dn-requestor-sender-name: The name that should be used for the From: line.
  • a4dn-requestor-subject: The text to use for the email's Subject.
  • a4dn-internal-smtp-view: The Static Web Content page to use for the email that is sent to an internal user.
  • a4dn-internal-sender-address: The email address that should be used for the From: line.
  • a4dn-internal-sender-name: The name that should be used for the From: line.
  • a4dn-internal-subject: The text to use for the email's Subject.

The views can be plain html or Razor templates (first character must be an @). Either way, Mandrill Merge Tags can be used in the markup to insert values from the form fields. This makes it possible to use the same template markup for either Mandrill or SMTP. Mandrill's formatted date syntax and conditional/looping syntax are not supported, but the tags SUBJECT, FNAME, LNAME, EMAIL, and CURRENT_YEAR are.

If a Razor template is used, the model will be a NameValueCollection object whose keys are the same as the Mandrill Merge Tags. Eg, the form field FirstName can be inserted in Razor using @Model["FIRSTNAME"], or in either type of template using Mandrill's *|FIRSTNAME|* syntax.

The Subject strings can also use Mandrill Merge Tag markup, which allows the subject line to be personalized using fields submitted with the form.

SMTP use also requires that the website's web.config be set up to specify an SMTP server. See system.net/mailSettings/smtp.

Categories
Search
Popular Tags
Hot Topics
Close