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:
- 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 amulti-line plain text field (NOT rich text)
- Create your form using any HTML editor you wish ensuring that ALL form elements have a unique ID.
- 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.
- 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 StratusFormsInitializemethod, 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());
}
}
People Pickers (SharePoint 2013 and above only)
People Pickers in SharePoint are based on divs and not text boxes, so in order to create a People Picker in StratusForms you need to create a div element with an attribute “data-StratusFormsType” equal to “PeoplePicker” as in the example below:
<div id="myID" data-StratusFormsType="PeoplePicker"></div>
You can promote a PeoplePicker field to a Person field in a SharePoint list by using the listFieldName attribute and setting it equal to the internal field name of a Person field in your SharePoint list.
<div id="myID" listFieldName="<internal field name of person field>" data-StratusFormsType="PeoplePicker"></div>
When using the PeoplePicker you need to be sure to include the SharePoint client libraries in which are needed for the functionality to work:
<script type="text/javascript" src="/_layouts/15/clientforms.js" ></script> <script type="text/javascript" src="/_layouts/15/clientpeoplepicker.js" ></script> <script type="text/javascript" src="/_layouts/15/autofill.js" ></script> <script type="text/javascript" src="/_layouts/15/clienttemplates.js" ></script>
When using the SharePoint client libraries, you need to make sure the files are loaded before you execute script that utilizes these libraries. So, where you previously may have used $(document).ready you would need to use ExecuteOrDelayUntilScriptLoaded instead:
ExecuteOrDelayUntilScriptLoaded(Init,"SP.js");
function Init()
{
//StratusForms Initialization code goes here
}
Setting PeoplePicker Field programatically
Finally, there is built in functionality to set the value of a PeoplePicker to a specific user. The function “StratusFormsAddCurrentUserToPeoplePicker” can be used to either set the value of the PeoplePicker to the current user or to another specific user using the user’s ID:
//to set people picker to value of current user:
$("#<id of people picker div>").StratusFormsAddCurrentUserToPeoplePicker();
//to set people picker to value of another user:
$("#<id of people picker div>").StratusFormsAddCurrentUserToPeoplePicker(<id of user>);
File Upload Support (SharePoint 2013 and above only)
StratusForms does not have support for uploading attachments to a SharePoint List. Instead, StratusForms has built in functionality to support uploading documents to a Document Library that is associated with your form. By using a Document Library instead of list attachments, users can take better advantage of metadata and search for those documents. To use the file upload functionality in StratusForms, following these steps:
- Create a document library to store your files
- Within that document library create a lookup field that is a lookup to your StratusForms list
- In your HTML for your StratusForms form, place the following HTML where you want the file upload to be on the form:
<div class="SFDontSave" id="<unique ID>" data-StratusFormsType="File"
data-StratusFormsFileOptions="{libraryName:'<name of document library>',
lookupField:'<internal name of lookup field in document library>',
displayOnly:false}"></div>
Where the parameters are:
- libraryName: Name of the document library you created to store your files
- lookupfield: Internal field name of the lookup field you created in the document library
- displayOnly: If set to “true” users will see a list of clickable links for the uploaded files for the current form, but not see upload functionality. If set to “false” users will see a list of clickable links for any previously uploaded files AND an file upload element to upload new files.
*files are not actually uploaded to the document library until the user submits the form to save/update it*