StratusForms is feature packed, allowing you to create almost any form you can imagine and look exactly the way you want it to look. For detailed examples, download the source code from Github at: https://github.com/mrackley/StratusForms

Basic Usage (Getting Started)

StratusForms works by taking all of the form data from a standard HTML form and storing it in one field in a SharePoint list as a JSON object. This allows users to create forms that look exactly how they want them to look and add complex business logic using JavaScript. In addition to simply storing the form data in a single field in a SharePoint List/Library, users can also “promote” fields in their form to SharePoint List fields.

StratusForms also comes with a myriad of features, helper functions, and possiblities! To get started follow these easy steps:

  1. For the list or library you wish to create forms for, create a column on that list or library named “StratusFormsData”. This field must be a multi-line plain text field (NOT rich text)
  2. Create your form using any HTML editor you wish ensuring that ALL form elements have a unique ID.
  3. Reference the core StratusForms file, StratusForms data library, jQjuery, and the SPServices library (needed for the free version of StratusForms) in your HTML files or pages.
  4. Include the JavaScript snippets to Load the form and Submit the form.

Below is an example of a simple form with just one field being stored to a list called “minimal”

<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.8.3/jquery.min.js"></script> 
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/jquery.SPServices/0.7.2/jquery.SPServices-0.7.2.min.js"></script> 
<script type="text/javascript" src="../SiteAssets/stratus-forms-1.3.js"></script>
<script type="text/javascript" src="../SiteAssets/stratus-forms-data-SPServices-1.3.js"></script>

<script type="text/javascript">
      //LOAD THE FORM
      $(document).ready(function() {
          $("#minimal").StratusFormsInitialize({
                queryStringVar: "formID",
                listName: "minimal",
                completefunc: function() { 
                }
          });
      });

      //SAVE THE FORM
      function SubmitForm()
      {
           $("#minimal").StratusFormsSubmit({
                listName: "minimal",
                completefunc: function(id) { 
                     alert("Save was successful. ID = " + id);
                     window.location = window.location.pathname + "?formID=" + id; 
                }
           });
       }
</script>

<div id="minimal">
     Title Field: <input type="text" id="title" />
     <br>
     <input type="button" onclick="SubmitForm();" value="Add/Update Entry" />
</div>

*Pro Tip* If you are just getting started with StratusForms I STRONGLY urge you to start simple and add complexity as you go. At first, don’t promote any fields to your SharePoint list, add a few fields at a time. Don’t add complex JavaScript until you know your basic form is working.

Now that you have a basic form functioning let’s start digging in and discovering all the features and functions of StratusForms.

(Documentation is *not* complete and is being updated regularly.)

Load Form – StratusFormsInitialize

To load a display or edit form use the StratusFormsInitialize method. This method is executed on the Div that the forms is contained in allowing for multiple forms on the same page.

 $(CONTAINING DIV).StratusFormsInitialize({
	     	queryStringVar: String,
	     	listName: String,
	     	completefunc: function() { 
		}
	     });

queryStringVar – Query string variable that contains the ID of the item you are displaying/editing
listName – The name of the list the item is stored in
completefunc: Code that is executed after the form is done loading.

 $("#myDiv").StratusFormsInitialize({
	     	queryStringVar:"formID",
	     	listName: "My List",
	     	completefunc: function() { 
                     alert("form loaded");
		}
	     });

Create/Update Form – StratusFormsSubmit

To Create or Update a form use the StratusFormsSubmit method. This method is executed on the Div that the forms is contained in allowing for multiple forms on the same page. In addition you can adjust the x and y axis for the validation error messages for fields by setting the errorOffsetTop and errorOffsetLeft properties.

An item is created if no query string variable exists for the query string parameter identified in the StratusFormsInitialize method, otherwise the item with the corresponding ID will be updated.

 $(CONTAINING DIV).StratusFormsSubmit({
	     	listName: String,
	     	errorOffsetTop: Number,
	     	errorOffsetLeft: Number,
                completefunc: function(id) { 		
		}
	     });

listName – The name of the list the item is to be stored in
errorOffsetTop – Adjust the Y axis of the alert validation messages
errorOffsetLeft – Adjust the X axis of the validation error messages
completefunc: Code that is executed after the form is done saving.

$("#myDiv").StratusFormsSubmit({
	     	listName: "My List",
	     	errorOffsetTop: 10,
	     	errorOffsetLeft: 5,
                completefunc: function(id) { 
		     alert("Save was successful. ID = " + id);
		     window.location = window.location.pathname + "?formID=" + id; 
		}
	     });

Promoting Fields to a SharePoint List – ListFieldName Attribute

With StratusForms you can create complicated forms without having to create an associated SharePoint list field for each field on your form. This is great for large and complex forms. However, you can promote any field on your form to a SharePoint list field so that field information can be used with list views and workflows. This is achieved using the ListFieldName attribute. If the ListFieldName attribute exists in a field element, StartusForms will attempt to promote that StratusForms field to a SharePoint list field whose internal name is equal to the value of the attribute.

 <input id="Element ID" type="text" ListFieldName='Internal Field Name' />

Promote the Email field on your form to the Title field in your SharePoint List

<input id="email" type="text" validate="validEmail" ListFieldName='Title' />

StatusForms supports promoting special field types to SharePoint fields as well including Person fields (SharePoint 2013 and 2016 only), Lookup Fields, and Date fields.

*Pro Tip* You can promote any field in your form to a SharePoint List field. However, it is suggested that when creating the fields for your SharePoint list that you use Single Line of Text fields especially for fields like Radio Buttons and Choice fields. This will save you time debugging your forms.

Required Fields / Custom Field Validation

With StratusForms you can easily mark a field as required by adding the class of required to your field. StratusForms will parse all the fields with the class of required when a form is submitted. If any required fields are missing values, StratusForms will inject an floating div with a class of “error” above the offending field when a form is submitted. If any div exists on the form with a class of “error”, Stratusforms will abort form submission. The position of this error message may be adjusted using the errorOffsetTop and errorOffsetLeft parameters in the StratusFormsSubmit method.

<input id="test" class="required" type="text" />

In addition to specifying a field as required, StratusForms has built in field validations for several field types. These validation functions can be used in conjunction with or independently from the required field functionality. The error messages for failed field validation work the same as the required field error messages.

Date Validation

<input id="date" type="text" validate="validDate" />

Email Validation

<input id="email" type="text" validate="validEmail" />

Social Security Validation

<input id="ssn" type="text" validate="validSSN" />

Phone # Validation (US)

<input id="phone" type="text" validate="validPhone" />

Custom Validation

In addition to using the built in field validations, you can create your own custom field validation functions in JavaScript.
These functions should take the following parameters:

value – The value of the element
element – The element being validated
offsetLeft – A number that can be used to position the x axis of the error message relative to the element
offsetTop – A number that can be used to position the y axis of the error message relative to the element

In order to execute this field validation, simply set the validate attribute to the name of your function for your field in StratusForms.

function MyCustomValidation(value, element, offsetLeft, offsetTop) {

}
 <input type="text" id="myID" validate="MyCustomValidation" /> 

The validation functions for each field are executed when you submit your StratusForms form. You can choose where and how to display the validation error to the user. However, StratusForms will not abort the form submission unless a “div” with the class of “error” exists for your form. Upon subsequent submits, StratusForms removes all of these error divs and performs the validations again.

The following is an example function to validate the date field. Notice the creation of a div with the class “error” and the positioning of the div using the offsets.


function validDate(value, element, offsetLeft, offsetTop) {
     if (!(!/Invalid|NaN/.test(new Date(value)))) {
         var position = $(element).position();
         $(element).after("<div class='error'>ENTER A VALID DATE.</div>");

         var myDiv = $(element).next("div");

         $(myDiv).css("position", "absolute");
         $(myDiv).css("left", position.left + offsetLeft);
         $(myDiv).css("top", position.top - offsetTop);

     } else {
         var thisDate = new Date(value);
          $(element).val(thisDate.getMonth() * 1 + 1 + "/" + thisDate.getDate()
              + "/" + thisDate.getFullYear());
     }
}