Vanilla Fix™ Setup and Deployment Guide

Vanilla Fix follows widely known methods to customise SharePoint forms. At a high level, deploying front-end enhancements to a SharePoint site involves loading commonly required artefacts plus list- or library-specific customisation files to a designated location, typically Site Assets. Detailed steps are illustrated below.


Contents

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.


First-time setup

One-off plumbing of common artefacts

From the Vanilla Fix Github repository, download the .js, .css, and .html files into a local folder. Also head over to the jQuery website and download the latest stable version of jQuery, that is, jquery-x.x.x-min.js.

Navigate to a SharePoint site designated for development and testing as an administrator with full-control rights. Upload vf-sp.js, vf-sp-styles.css, and the jQuery file to the Site Assets library of this SharePoint site. If necessary, put these files in a dedicated folder under Site Assets.

Note. If you foresee a need to customise forms in multiple lists across multiple sites in a SharePoint site collection, consider deploying the above files to the site collection’s root (top-level) Site Assets library instead, as long as all target users have visibility to it.

The steps so far are one-off and need not be repeated for the same SharePoint site (or site collection if these common artefacts have been deployed to site collection root).

Preparing an individual list for form customisation

Pick a SharePoint list to customise. In the case of Office 365 (SharePoint Online), be sure to apply Classic experience from the Advanced Settings of the list.

Before exiting Advanced Settings, you may also want to disable quick property editing. With this turned on, users may be able to bypass your data validation.

Next, locate vf-list-boilerplate.html downloaded earlier from the Vanilla Fix Github repository. Duplicate this file to create a copy. Name the copy such that it identifies the chosen SharePoint list. For example, if the list is called “Travel Requests”, then you would name the file “vf-list-travel-requests.html”. From now on, this file is referred to as vf-list-{name}.html.

Open vf-list-{name}.html in a text editor. Ensure that the paths to jQuery, vf-sp.js, and vf-sp-styles.css that were deployed earlier are correctly specified relative to the location of the SharePoint list. Save any changes.

Next, upload the vf-list-{name}.html file to the Site Assets library of the current SharePoint site in which the list is located. If the SharePoint list belongs to a subsite, then vf-list-{name}.html needs to be placed in the Site Assets library of that subsite, regardless of where vf-sp.js and vf-sp-styles.css are located.

Once vf-list-{name}.html is in place, navigate to the SharePoint list itself in the browser. Change the URL to open the list’s DispForm.aspx (or Forms/DispForm.aspx in the case of a library). Edit this page through the settings menu.

Next, add a Content Editor web part to the page.

Note. In Office 365 (SharePoint Online), Content Editor as a type of web part may not be available initially. If so, refer to this Microsoft article.

In the web part settings, set Content Link to point to vf-lst-{name}.html located in Site Assets. Be sure to give the correct relative path to it, and click OK.

If everything has been pieced together correctly, a JavaScript alert pops up to say that Vanilla Fix is in place. With the exception of this alert, however, the SharePoint list behaves exactly the same as before.

You may also want to inspect your browser’s console for the key properties of the instantiated Vanilla Fix object.

You are now done editing DispForm.aspx of the list. Close the page and repeat the steps performed on DispForm.aspx, to insert identical Content Editor web parts into NewForm.aspx and EditForm.aspx of the same SharePoint list.

When done, re-open vf-list-{name}.html in a text editor and set the vf.pulseCheck property to false. It is a good idea to also set the rest of the Vanilla Fix object properties, such as the names of the target SharePoint site and list, as you see fit. Save the changes and re-upload the file to Site Assets.

Note. Specifying Content Link inside the three Content Editor web part instances is a one-off task for each SharePoint list. Once this has been configured across the three .aspx pages, vf-list-{name}.html is the only file that needs to be worked on going forward. There is no need to open and edit DispForm.aspx, NewForm.aspx, or EditForm.aspx of the same list again, that is, unless you are migrating the list to a different environment.

At this point, Vanilla Fix has been wired to your SharePoint list successfully, although no visible form customisation has been made yet. Changes to the behaviour of DispForm.aspx, NewForm.aspx, and EditForm.aspx for this particular SharePoint list are made each time vf-list-{name}.html is re-uploaded to Site Assets. Now that all prepatatory steps have been carried out, the remaining work is:

  • defining columns (form fields) required for the SharePoint list; and
  • iteratively modifying vf-list-{name}.html to apply appropriate front-end enhancements.

Table of contents


Production deployment

Form customisation is done on a list-by-list basis. Deploying front-end enhancements made to a SharePoint list basically comes down to publishing up-to-date vf-list-{name}.html to Site Assets.

This is on the assumption that all required wiring is in place. For a first-time deployment to a different SharePoint tenant, installation, site collection, or site, you must ensure that these prerequisites have been completed:

  • The SharePoint list in the target environment has column defintions and list settings that match those of the source list.
  • Each of the three .aspx pages that belong to the target SharePoint list has a Content Editor web part with the Content Link property correctly pointing to vf-list-{name}.html; this is a one-off task for the target list instance.
  • Common Vaniilla Fix artefacts, such as vf-sp.js, have been deployed to the target environment and are correctly referenced in vf-list-{name}.html; this is a one-off task for the target SharePoint site or site collection.

Important: Ensure that the common artefacts, that is, vf-sp.js, vf-sp-styles.css, and jQuery, in the target environment are identical to the ones used during development and testing.

Table of contents


Production deployment: alternate methods

If content preservation is not an issue, the following alternate methods are available for the migration of form customisation work:

Form customisation is carried over in each of the above operations.

For list-by-list migration, you can save your customised list as a template (.stp), either with or without content. This preserves the list column definitions so you don’t need to re-create them. You do, however, need to deploy the common artefacts and vf-list-{name}.html manually.

Table of contents


Next

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