Vanilla Fix™ Design Patterns: Conventions and Recommended Practices

This article is a part of Vanilla Fix Design Patterns and How-To’s.

Vanilla Fix is an open, flexible tool for form customisation that respects how you as a front-end developer prefer to devise and implement the functionality you want. Before getting into the various kinds of front-end enhancements that are possible with Vanilla Fix, however, it helps to know a few conventions that help keep your enhancements easy to read amd maintain.

jQuery instead of $

jQuery is often the only JavaScript library used in a project involving Vanilla Fix. However, that is not always the case. To prevent conflicts now and in the future, stick to the jQuery name in JavaScript instead of the $ alias.

JavaScript variables and properties

There are three broad scopes of JavaScript variables and properties in Vanilla Fix.

  • Properties of the default VanillaFix object instantiated in vf-sp.js are treated as Vanilla Fix-wide variables and are prefixed with vf.; for example, vf.formMode. Some of these can be reset after object instantiation. These properties are accessible equally to all SharePoint lists that use Vanilla Fix.
  • Variables declared in vf-list-{name}.html but outside any of its functions are list-level variables. They are typically representative of the columns and other characteristics of the individual SharePoint list. The name of a list-level variable is prefixed with a single underscore.
  • Variables declared in a function are local to that function. Their names are not prefixed with underscores.

vf.formMode equals 0, 1, or 2

Among the object properties defined in vf-sp.js is vf.formMode. This is used to identify the .aspx page that is being loaded. By convention:

  • view mode” = DispForm.aspx (vf.formMode 0)
  • edit mode” = either NewForm.aspx (vf.formMode 1) or EditForm.aspx (vf.formMode 2)

To have a routine in vf-list-{name}.html that kicks in only in certain modes or forms, wrap it in an if statement that examines vf.formMode, as in the following example:

//-- Fix VF-1 [Use of __formMode]
if (vf.formMode==0) { // View mode (DispForm.aspx) only
}
if (vf.formMode>=1) { // Edit mode only
if (vf.formMode==1) { // Specifically NewForm.aspx only
}
if (vf.formMode==2) { // Specifically EditForm.aspx only
}
}

List-agnostic methods in the VanillaFix class

Methods inside the VanillaFix class are re-usable across all copies of vf-list-{name}.html. The names of these methods are vf.-prefixed to indicate that they are from the VanillaFix class; for example, vf.getText() and vf.applyCustomLayout(). Any new re-usable, list-agnostic methods that you introduce into your own solutions can go into either the default VanillaFix object instance (vf) or a new object that extends the Vanilla Fix class. Also refer to “Extending the common Vanilla Fix artefacts” down below.

Run-once vs. run-on-demand

To ensure clarity and consistency in deliverables, you should be mindful of rotines that run once per page load, versus ones that can be fired up on demand. To summarise:

  • All object methods from vf-sp.js may be run multiple times as required throughout a page load.
  • initialiseForm() is run once. Any routines going inside initialiseForm() are designed to be run only once in a page load.
  • Individual field-bound functions defined within registerFormEvents() can run multiple times as they respond to what the user does. Note that registerFormEvents() itself is called only once inside renderForm(), and nowhere else.
  • Edit mode only: PreSaveItem() is a SharePoint function designed for data validation before submission. It is called when the user chooses to save their form data or triggers an event that leads to a save. PreSaveItem() may be invoked multiple times until it returns true, that is, data validation is successful.

There may be cases where identical sets of steps need to be carried out at the beginning of a page load and also on demand as driven by events. If so, create a function that contains these steps and then call it from both initialiseForm() and a field-bound event.

Refer to the Vanilla Fix Architecture article for an overview of how the different components are pieced together.

Avoid repeated hard-coded strings

Asking a developer to avoid repeated occurrences of identical hard-coded strings is very much stating the obvious. However, it is a frequently overlooked principle when locating form elements in jQuery syntax. Take every opportunity to reduce maintenance around hard-coded values in JavaScript. At a minimum, always assign field display names to variables so that changes to list column defintions will not wreak havoc mid-project. A basic pattern is to create list-level variables for field names at the beginning of vf-list-{name}.html as in the following example:

//-- Fix VF-2 [Field display names as variables]
var _labelTitle="Title"; // Yes, even Title should not remain hard-coded.
var _labelEngagementType="Engagement Type";
var _labelEngagementLocation="Engagement Location";
var _labelNumberOfHours="Number of Hours";
var _labelRate="Rate";
var _labelEngagedAmount="Engaged Amount";
var _labelApplicableTax="Applicable Tax";
var _labelInvoicedAmount="Invoiced Amount";

// Later on, field properties can be accessed in this way:
jQuery("input[title^='"+_labelApplicableTax+"']".val()

When in doubt, sanitise text

Reading in the contents of an input field or a table cell, and then performing some routine based on those contents, can be a risky operation. That is because your browser tends to give you the raw stuff complete with line breaks, tab stops, trailing spaces, and other invisible characters that will almost certainly get in your way. Do not easily trust what your user or browser gives you. When in doubt, sanitise text input with vf.getText() before doing performing string operations. Here are a couple of examples:

//-- Fix VF-3 [Sanitising text]
var tableCellContents=vf.getText(
jQuery(vf.getField(_labelSomeField)).closest("td").text()
);
_userSetStreetAddress=vf.getText(
jQuery("input[title^='"+_labelStreetAddress+"']").val()
);

Extending the common Vanilla Fix artefacts

The common Vanilla Fix artefacts in the GitHub repository will be updated from time to time in a backward-compatible manner.

As a frone-end developer you are free to tweak, improve, and extend vf-sp.js and vf-sp-styles.css as you see fit across your projects. Be very careful, however, with version control of your modifications, and always ensure that you deploy identical files across all SharePoint environments under each project.

An alternative is to take a set-and-forget approach, and simply avoid modifying these files directly. Instead, add your own functions, methods, variables, properties, styles, and other re-usable resources in separate files and deploy them alongside vf-sp.js and vf-sp-styles.css. Be sure to get your re-usable artefacts recognised in each of your vf-list-{name}.html‘s.


Back to Vanilla Fix Design Patterns and How-To’s

Questions and thoughts about Vanilla Fix can be sent to vanillafix@kimmaker.com