Vanilla Fix™ Architecture

Contents

  1. Vanilla Fix components
  2. What goes on under the hood
  3. Page load sequence

Note. In SharePoint terms, the subject of form customisation is an individual SharePoint list or library. For the rest of this article, a “list” can also mean a library, except where caveats are given.


Vanilla Fix components

In Vanilla Fix, form customisation logic goes into vf-list-{name}.html, which is named after the SharePoint list it customises. A project incorporating front-end enhancements across five different SharePoint lists, for instance, would produce five vf-list-{name}.html‘s.

Click image to enlarge

Supporting this is a set of deploy-once common artefacts, as follows:

  • vf-sp.js: The foundational JavaScript file that contains object properties and methods for form customisation, encapsulated in the VanillaFix class definition;
  • vf-sp-styles.css: Styles required to render customised list forms, some of which override out-of-the-box SharePoint specifications;
  • jquery-x.x.x.min.js: The latest stable version of jQuery downloaded at the beginning of each Vanilla Fix project; the recommendation is to use 3.3.1 and above.

A single project may span across multiple SharePoint environments along its chosen development lifecycle, such as Proof of Concept (PoC), Development, Staging, and Production. An “environment” may be a SharePoint tenant, installation, site collection, or site, depending on how your SharePoint platform is organised.

Regardless of how many environments your project has, it is important that you keep your common Vanilla Fix artefacts (vf-sp.js, vf-sp-styles.css, and jQuery) identical across all of them. Any modifications to these files made in a Development environment, for example, must be propagated down to all other environments provisioned for the same project.

The intent, however, is that there should not be much of a need to modify these common artefacts once they are in place. That is because all customisation logic controlling the behaviour of a specific list form goes into vf-list-{name}.html, which is bound to an individual SharePoint list.

That said, you as a developer are free to add your own JavaScript functions, global variables, object methods, properties, styles, and images that are re-usable across your form customisation project. Still, the recommendation is to place additional files alongside the default common artefacts and then have them wired to your vf-list-{name}.html(s), as opposed to modifying the original artefacts directly.

Table of contents


What goes on under the hood

There are three forms in each SharePoint list: DispForm.aspx for displaying item data, NewForm.aspx for item creation, and EditForm.aspx for editing existing item data. Normally, front-end enhancements to all three are delivered by a single vf-list-{name}.html created for that particular SharePoint list.

“View mode”

On DispForm, Vanilla Fix intercepts the out-of-the-box SharePoint rendering and applies customisation logic to produce its own rendering of the list form, which is then shown to the user for consumption. This flow, referred to as view mode in Vanilla Fix-speak, is illustrated below:

“Edit mode”

Both NewForm and EditForm follow the flow illustrated below. SharePoint loads form data, but Vanilla Fix applies its customisation logic and wires field events before giving the final rendering to the user. The user interacts with the form and triggers prescribed events. Upon Save or an equivalent action, Vanilla Fix performs its own data validation and transformation as required, before handing back control to SharePoint for submission and further processing.

Click image to enlarge

Table of contents


Page load sequence

When DispForm.aspx, NewForm.aspx, or EditForm.aspx is loaded with Vanilla Fix, it goes through a series of resource and function calls as described below:

  1. The .aspx page calls vf-list-{name}.html through a Content Editor web part.
  2. vf-list-{name}.html calls jQuery, vf-sp.js, and vf-sp-styles.css. As a result, Vanilla Fix object properties, methods, and styles are made available.
  3. vf-list-{name}.html defines list-level JavaScript variables that persist through the rendering of the list form.
  4. vf-list-{name}.html adds renderForm() to SharePoint Body OnLoad function names, so that it is executed on page load.
  5. renderForm() is executed and calls initialiseForm(). This function performs initial visibility control and formatting of form elements. Each of the three form modes (DispForm, NewForm, and EditForm) may have its own specific routines and sub-routines in this initialisation call.
    • If the SharePoint list is configured to use a custom form layout via Vanilla Fix, then the custom layout is applied at this point. In this case, the custom layout is defined within vf-list-{name}.html as an HTML structure with placeholders for the list fields.
  6. renderForm() also calls registerFormEvents(). Any events (triggers and actions) wired to the fields are defined here.
  7. Vanilla Fix completes rendering the form, and the user is able to see and interact with the customised .aspx page. The form responds to user actions when predefined events are triggered.
  8. Edit mode (NewForm and EditForm) only: When the user asks to save their form data, PreSaveItem() kicks in to perform Vanilla Fix-initiated validation, conversions, and/or calculations to ensure acceptable format and quality of data. Upon successful quality assurance, control is handed over to SharePoint.

Table of contents


Next

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