Vanilla Fix™ Object Reference

This article is part of Vanilla Fix™ documentation.

Contents

Object instantiation

The vf-sp.js file, which gets deployed to Site Assets, defines the VanillaFix class and also instantiates a default object as vf, to make its properties and methods available to form customisation routines. Each list-specific vf-list-{name}.html file then sets the foundational object properties that are applicable to the SharePoint list it customises. These properties, which can be set individually, are as follows:

  • platform: Either “Online”, “2016”, “2013”, or “2010”; defaults to “Online” if no valid choice is specified. This affects other object properties, such as names of styles, which may be dependent on the intended target platform.
  • siteName: A short description of the SharePoint site in which the target SharePoint list resides; this is for information only, and serves no functional purposes other than logging.
  • listName: The name of the target SharePoint list; this is for information only, and serves no functional purposes other than logging.
  • locale: The language and region code, for example, “en-AU”, applied to the target list; this affects other object properties and methods that are based on the locale, such as ones related to localised literals and date formats. If not set, this property defaults to “en-GB”.
  • revision: An indication of the status or progress of form customisation for the given SharePoint list; no specific format is enforced. The developer is free to devise a convention that suits their project, such as date-stamps or incrementing integers.
  • isCustomLayoutUsed: Set to true if the given list form is configured to use a custom form layout; false by default.
  • pulseCheck: Set to true for initial testing of a newly created vf-list-{name}.html; false by default and for normal operation.

Once vf has successfully been instantiated, the above details and other relevant specifics, including the full URL and query string of the respective form, are logged to the browser’s console for diagnostic purposes.

It should be noted that the above-mentioned properties, in the given order, are also the constructor parameters for the VanillaFix class. As such, each vf-list-{name}.html can create a vf object directly as opposed to setting individual properties on an object already instantiated in vf-sp.js.

The main reason why vf is first instantiated in vf-sp.js without any constructor parameters and then vf-list-{name}.html subsequently sets list-specific properties in the object is because of backward compatibility. Vanilla Fix has switched to an object-oriented design since vf-sp.js Release 181210. By having a “default” instance of VanillaFix available in vf-sp.js and specifying how non-object-oriented Vanilla Fix variables and functions are mapped to their object-oriented equivalents, copies of vf-list-{name}.html that were written for “legacy” vf-sp.js are expected to also work with up-to-date, object-oriented vf-sp.js without any modifications.

If your project is not affected by legacy Vanilla Fix code, you are free to comment out the default object instantiation in vf-sp.js and then instantiate a vf object directly in your vf-list-{name}.html with appropriate constructor parameters. This, however, remains entirely optional and would not necessarily amount to meaningful performance gains.

Table of contents

Read-only properties

In addition to the above foundational properties, which can be accessed and set by vf-list-{name}.html, the VanillaFix class makes the following read-only properties available:

  • objectDate: The date and time, in the user’s current time zone, at object creation
  • formUrl: The full URL of the list form, which comes from window.location.href
  • queryString: The query string portion of the form’s URL, which comes from window.location.search
  • formMode: 0 if DispForm.aspx, 1 if NewForm.aspx, 2 if EditForm.aspx, and -1 if unknown
  • formModeLiteral: The literal representation of the currently set formMode, for example, “DispForm.aspx”
  • currentTimeZone: The time zone portion of objectDate
  • regExEmail: The regular expression pattern that can be used to validate an email address
  • daysOfWeek: An array of day-of-week literals; may be customised based on the object’s locale
  • field: The jQuery selector string for a form field label; may be customised based on the object’s platform
  • fieldValue: The jQuery selector string for the value of a field; may be customised based on the object’s platform
  • gotPulse: The message in the JavaScript alert that appears when the object’s pulseCheck property is set to true; may be customised based on the object’s locale
  • listForm: The jQuery selector string for the list form contents; may be customised based on the object’s platform
  • popUpIndicator: The SharePoint URL parameter to indicate whether the form should be rendered as a modal pop-up; “IsDlg=1” by default, but may be customised based on the object’s platform
  • renderingCompleted: The message that gets logged when Vanilla Fix has finished rendering the given list form; may be customised based on the object’s locale
  • renderingStarted: The message that gets logged when Vanilla Fix is ready to render the given list form; may be customised based on the object’s locale
  • reqIndicator: A programmatically generated mark to indicate that a field is required; ” *” by default, but may be customised based on the object’s locale
  • reqSpan: A reusable HTML span tag to mark a field as required, based on the object’s reqIndicator; may be customised based on the object’s platform and available styles

Table of contents

Methods

The VanillaFix class provides the following methods for form customisation. Detailed information and usage instructions are found in vf-sp.js.

  • appendCharacters(theString,theChars)
  • applyCustomLayout()
  • assembleTimeOfDayString(theFieldLabel,theSeparator)
  • convertToSortableDate(theDate,theSeparator,theLocale)
  • convertToSortableTime(theTime,theSeparatorIn,theSeparatorOut)
  • determineListName(theInput)
  • determineLocale(theLanguageAndRegion)
  • determinePlatform(theInput)
  • determineSiteName(theInput)
  • getField(theLabel)
  • getText(theInput)
  • getUrlParameter(theName)
  • produceSignature()
  • removeAppendedCharacters(theString,theChars)

Table of contents


The VanillaFix class can be extended to accommodate additional properties and methods required for your project.

Next

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