Vanilla Fix™ Design Patterns: Designing and Applying a Custom Form Layout

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

SharePoint. Front-end. jQuery. Functions. User experience. Data integrity. Newspeak. Not sure what these are? Stop reading, and do this instead.


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.

A judgement call

A standard SharePoint list form has a straightforward single-column layout that flows from top to bottom according to the column (field) order configured in list settings.

Usually, with some caveats, this is perfectly fine. Together with appropriate enhancements for individual fields or clusters of fields, the standard layout lets the person entering data and the person consuming it carry out their tasks with no major confusion or obstacles along the way. But then, there are cases where commanding flexibility in what gets rendered on the screen is a key part of the business objectives associated with a form.

The Standard SharePoint List Form Layout (Left) vs. A Custom Form Layout

A SharePoint list form can have a custom layout as part of its front-end enhancements. The reasons for designing and applying a custom layout, however, must be justified on a case-by-case basis. Here are the things a custom layout gives that the standard SharePoint list form layout does not:

  • Ability to group fields into logical sections, together with added visual guidance as required, independent of physical field ordering as configured in list settings;
  • Freedom to design an arbitrary HTML structure consisting of <div>s and <span>s, including support for one-, two-, or three-column placement of fields in each individual row;
  • Straightforward application of custom styles;
  • Rendering of form elements on a need-to-know basis (“hidden by default”), which translates to straightforward control in preventing exposure of information deemed unnecessary or irrelevant to the end-user or the state of the selected content item;
  • More efficient use of screen real estate and opportunity to reduce vertical scrolling;
  • Simplicity and flexibility in addressing concerns of ambiguity, misleading instructions, or lack of direction in the user interface; and
  • Freedom to create and place field labels that make sense to the user, irrespective of the actual field names understood by SharePoint.

Like all add-ons to life, however, there is a price to introducing a custom form layout to a SharePoint list. This deviation in design amounts to an additional layer of development and maintenance efforts upfront and down the line. Once a custom layout has been applied to a SharePoint list, it needs to be kept meticulously up to date with any field-related changes occurring in that list. Also, with great freedom of design comes a separate responsibility to ensure that the customised form renders correctly on all target devices, be they desktops, tablets, or mobiles.

Adopting a custom layout is ultimately a judgement call mostly on the form developer’s part. The most important thing is NOT the client’s desire to have a visually attractive form, but making a call on whether a custom form layout is highly likely to increase the efficiency with which target users handle data. Efficiency in this context is observed in things such as:

  • length of time taken to complete data entry on a single content item;
  • length of time taken from submission to consumption of form data;
  • number of failed save attempts before a successful submission; and
  • ability to understand and follow given instructions natively without specialised help.

The problem is that these metrics are difficult to measure or predict, both before and after rolling out a custom form layout. Unless the project sponsor has exceedingly deep pockets, a form developer cannot base their decision to go with a custom form layout on emprical research. In other words, it is simply difficult to determine scientifically if having a custom layout for a particular SharePoint list is the “right” thing to do.

Therefore, most form developers can only work with the tools and resources at their disposal, which typically boil down to carefully made assessments of:

  • existing business processes and their bottlenecks;
  • maturity of information management practices adopted by teams;
  • access to sources of help;
  • how much of a paradigm shift it is to handle data in SharePoint as a platform;
  • business outcomes the client aims to achieve through their new or enhanced SharePoint form;
  • time and resources allocated to form customisation work; and
  • if feasible, feedback on a very quick simulation of how a custom form layout might work for the client’s business process or register.

These are, of course, a description of what SharePoint form development consulting entails in general, and not a methodology that is exclusive to the discussion of custom form layouts. Such observations are translated into various design decisions influenced by the developer’s experience, philosophy, and level of empathy. At the end of the day, the use of a custom form layout in any given SharePoint list remains optional and a judgement call made strictly on a case-by-case basis.

Table of contents

Designing a layout

The method of applying a custom form layout in Vanilla Fix adopts a concept attributed to Mark Rackley, and develops it further for repeatability, portability, and consistency in implementation. A barebone custom layout is baked into vf-list-boilerplate.html, which can be activated on a list-by-list basis by setting the _isCustomLayoutUsed variable to true. Once activated, a primitive table structure appears in lieu of the original form, showing the Title field and a few dummy field labels. The change takes place across view and edit modes, that is, DispForm, NewForm, and EditForm.

This HTML structure is what needs to be customised to reflect the existing fields in the SharePoint list. The rest of the design process is as follows:

Use the barebone HTML structure included in vf-list-boilerplate.html as the starting point..

  1. Organise rows and cells with nested <div> tags. Each row can have either one, two, or three columns (“cells”). Each cell can be a placeholder for either a field label, a field control (a text box, for example), or visual guidance such as a separator or a section title.
  2. In each cell created for a field control, insert a <span> tag with a data-displayName attribute, and set its value to the display name of the respective field.
  3. In each cell created for a field label, insert a <span> tag and place the field label in it. Normally, this label is the display name of the respective field as defined in list settings. If the given field display name is potentially ambiguous or confusing to the user, however, the label can have different wording. Alternatively, the field display name itself can be modified from list settings. Which is more feasible and preferable is the form developer’s call.
  4. Assign appropriate ID’s to the <span>s in the custom layout. The recommendation is to devise a naming convention such that the ID of a field label begins with the ID of the corresponding field control. For example, if the span ID of the Customer text box is “formCustomer”, then the span ID of its label can be “formCustomerLabel”. This facilitates simpler operations for field visibility control. In the preceding example, actions on jQuery(“span[id^=’formCustomer’]”) apply to both the field label and control. (Be careful not to create unintended false-positives, though.)
  5. Apply appropriate styles to all <div> tags in the custom layout. Follow the observed convention where each row has its class attribute set to formDivRow. Each cell should have its class attribute set ot either formDiv1Col, formDiv2Col, or formDiv3Col, depending on how many columns the current row is split into. Additional styles may be defined and applied as needed.
  6. Add mandatory field indicators by inserting a <span> tag next to the label of each mandatory field. Set the class attribute to editMode so that these indicators are shown only in edit mode.
  7. Add necessary visual guidance such as separators and section titles to designated <div> tags.

Aside from the above guidance, the precise setup of each custom layout is up to how the form developer chooses to implement the look and feel prescribed by the client. Clearly, there is no WYSIWYG support as seen in Nintex Forms, InfoPath, and similar software offerings that get glued on to the back-end of the SharePoint platform. Designing a front-end custom form layout to client specifications is a straightforward task for any developer with HTML and CSS skills.

Table of contents

The implications of freedom

Applying a custom layout to a SharePoint list is a departure from conventional methods of SharePoint form customisation in a number of ways:

  • To make way for a custom layout, the entire out-of-the-box form is made invisible. As a result, individual fields are hidden until they have been specifically accounted for in the new HTML structure.
  • There is now much more flexibility in the display (or non-display) of individual fields and clusters of fields. It is largely an exercise of locating the right <div> or <span> by ID and carrying out whatever necessary operations against it. Still, the level of scrutiny required for data validation remains the same, and every mandatory field must be correctly accounted for.
  • Once a custom form layout has been applied to a SharePoint list and various front-end enhancements tailor-suited to that layout have been implemented, going back to the standard SharePoint list form layout is often difficult, both technologically and in terms of user experience. Decisions should be made early on, and end-users should not be asked to learn a new experience for the same SharePoint list if it is already in active use.

Accordingly, some general caveats follow:

  • Just because one SharePoint list has adopted a custom form layout does not mean other lists in the same SharePoint site should follow suit. Assessments need to be made on a list-by-list basis.
  • Related to the above point is that custom form layouts should not be seen or used as a vehicle for implementing consistent branding or corporate identity across multiple SharePoint lists. Branding and corporate identity in SharePoint are implemented through master pages and relevant site settings, not front-end enhancements.
  • As with controlling the visibility of individual fields, custom form layouts implemented on the front-end should NOT be used as a mechanism for restricting access to sensitive information. “Hidden” for the sake of clarity and convenience does not mean “protected.” Do NOT mix content items across multiple security classifications in a single SharePoint list.

Table of contents

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

Questions and thoughts about Vanilla Fix can be sent to