SharePoint modern view formatting with JSON – part 1 of 2

View formatting with JSON is here and ready to be utilised. You might be wondering what exactly it is and how it can benefit you and your users. Have you ever had a need or desire to change the look of a list or library in SharePoint but didn’t want to go down the coding route, or possibly was denied by the organisations governance policy as it was not out of the box functionality? Well, now you can style a list or library with JSON using out of the box functionality and create an amazing user experience.

JSON (JavaScript Object Notation) is a data format that is readable by many, if not all programming languages. I want to provide you with a comprehensive understanding of how we can use JSON to change the view of a list or library to get the desired look. I’ve split this post into 2 as we have a lot to cover.

By the end of this 2-part tutorial, we’ll turn this ordinary looking SharePoint list….

  Into this

Fundamentals 

Reading JSON

It is important that you understand JSON as that is what is used to create these custom views. JSON data is written as name/value pairs which must be in double quotes around both name and value. The only time this does not occur is when a true or false value must be specified.

Example:

{   
    "Name" : "Alice",
    "Department" : "Accounts",
    "PermissionLevel" : "Edit",
    "hideSelection" : true
}

Further learning

If you feel like you need more knowledge before we start you can find excellent introductory resources on the internet to help if you have not used JSON before. I would recommend these to pick up the basics.

• JSON Syntax – W3 School
• JSON Tutorial: Learn JSON in 10 Minutes

Writing the syntax relies on you having a basic understanding of HTML and CSS as you will create HTML elements and style them with CSS. If you have not crossed paths with either of these the following resources will help you gain a greater understanding.

• HTML – w3schools
• CSS – w3schools

Basics of formatting a view

When formatting a view for a list or library it is important to understand that there are 2 different methods to pick from depending on what requirements need to be met.

additionalRowClass

This is to be used when you only want to concentrate on one column in the list or library. Using it will apply a CSS class to a single column on each row, you can set the class to be default behaviour or you can use an ‘if statement’ so the class will only be applied if a condition is met. Examples include

• You would use an ‘if statement’ if a due date column is passed today’s date then the condition will be met and highlight that particular column with a red background.
• If you need a picture column in a list to have the width & height of 200px on all pictures you would use addtionalrowclass without an if statement.

rowFormatter

This works by creating an element for each list item (for the tutorial you’ll use a div element) from there you can customise every row by using CSS to get the layout you want. Examples include

• You want to style every list item in a contact list as a contact card

Note: If you use additionalRowClass and rowFormatter together any styling applied by additionalRowClass will be overridden by rowFormatter so use one or the other.

There are 2 true/false values that can optionally be set to enhance the user experience. If you choose not to add them in the default is false.

HideSelection

• True = the user will not be able to select the item in the list or library
• False = the list item will be able to be selected by the user

Hidecolumnheader

• True = the column headers on the list or library will not be visible
• False= the column headers list or library will be visible

Planning the view

An important first step before writing any JSON is to figure out how you want the view to look. In this tutorial, we are going to build a meeting venue list as shown above.

The first step is to build a custom SharePoint list with the following columns

• Title (default) – single line of text
• Address – single line of text
• Rating – choice
• Maximum capacity – number
• Venue link – hyperlink
• Price – currency
• Picture – picture

Once the list has been created with the columns fill it with data.

Now work can be started on transforming the view from an idea to reality.

Writing JSON

Structure 

A structure is required to hold the columns that will display the data. The way that we’ll achieve this is by creating a div (division) that will hold 3 nested child divs. Those 3 child divs will be the columns that hold all the list values.

I highly recommend downloading Visual Studio code to help you with this, I’ll be using it through the tutorial.

Create a new file in Visual Studio code and save it as a JSON file.

Next, write the schema. Open curly brackets and copy the following snippet

{    
"$schema": "https://developer.microsoft.com/json-schemas/sp/view-formatting.schema.json"
}

This is written in so intellisense will work inside visual studio code, it makes it easier to write the JSON that we need to write. To access intellisense at any time press ctrl+Space

No intellisense
Intellisense

Press ctrl+space inside a new line of the curly brackets and add the following

• “hideSelection”: true,
• “hideColumnHeader”: true,
• “rowFormatter”: {}

You should have this

{    
   "$schema": "https://developer.microsoft.com/json-schemas/sp/view-formatting.schema.json",    
   "hideSelection": true,    
   "hideColumnHeader": true,   
   "rowFormatter": {

                   }

}

Press ctrl + space in the rowFormatter curly brackets and you’ll get a new set of elements to select from

Using intellisense you can see there are 7 different elm types to choose from

Add the elmType and set it to a div then add style and attributes, this will create the main div.

A style is used to style the elm type, attributes is used to provide additional information about the element.

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/view-formatting.schema.json",
  "hideSelection": true,
  "hideColumnHeader": true,
  "rowFormatter": {
    "elmType": "div",
    "_comment_": "MAIN DIV",
    "attributes": {},
    "style": {}
  }
}

Comments

In JSON there is no inline commenting like when working with other languages which makes it difficult to follow with each new line you write.
There is a workaround – You can create a custom property as long as the name does not clash with existing property names already being used. So below each div I create I will write “_comment_” : “write my comment here”.

note: It will show up as an error in visual studio code but it will not cause any issues when added to the list/library view.

Child elements

Now 3 child div’s need to be created so they are nested inside the main div.

To nest an element in another element use the ‘children’ object. It is important to understand the children object as nesting is a common requirement when working with view formatting. The element “children” must open and close with square brackets [] as it is classed as an object in JSON. Study the snippet below to see how to apply it correctly.

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/view-formatting.schema.json",
  "hideSelection": true,
  "hideColumnHeader": true,
  "rowFormatter": {
    "elmType": "div",
    "_comment_": "MAIN DIV",
    "style": {},
    "attributes": {},
    "children": [
      {
        "elmType": "div",
        "_comment_": "DIV ONE",
        "style": {},
      },
      {
        "elmType": "div",
        "_comment_": "DIV TWO",
        "style": {}
      },
      {
        "elmType": "div",
        "_comment_": "DIV THREE",
        "style": {}
      }
    ]
  }
}

Styling the structure

Adding this JSON to the list/library view right now you’ll just see a blank list as the JSON is overriding the view but has not been given any styling.

If you are a developer then writing CSS for the style may be a viable option but for the rest of us this can be a very time consuming and frustrating task, so I am going to suggest different approaches.

1. You can search on the internet and find someone that has already written a JSON view and modify their style to fit your needs because there is no need in reinventing the wheel if something is already out there in the public domain and not under copyright.
2. Use a CSS generator, there are plenty about online. You can use a flexbox generator which generates the CSS for you. I wanted flexbox’s to style each div to give our list item the desired look & also make the list item responsive for mobile viewing. Just input the parameters on the website and copy the generated CSS from the site to inside the relevant style attributes in the JSON.

Item background

The list items will stand out better if there is a background colour. This can be achieved with a class in the attribute element of the main div. Using a theme from the options at Microsoft SharePoint theme colours keeps the list item consistent with SharePoint branding.

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/view-formatting.schema.json",
  "hideSelection": true,
  "hideColumnHeader": true,
  "rowFormatter": {
    "elmType": "div",
    "_comment_": "MAIN DIV",
    "style": {
      "display": "flex",
      "flex-wrap": "wrap",
      "align-items": "stretch",
      "flex-direction": "row",
      "padding": "20px",
      "margin-bottom": "16px",
      "max-width": "930px",
      "border-radius": "8px"
    },
    "attributes": {
      "class": "ms-bgColor-neutralTertiaryAlt"
    },
    "children": [
      {
        "elmType": "div",
        "_comment_": "DIV ONE",
        "style": {
          "flex-grow": "1",
          "display": "flex",
          "flex-direction": "column",
          "flex-wrap": "nowrap",
          "align-items": "stretch",
          "max-width": "260px"
        }
      },
      {
        "elmType": "div",
        "_comment_": "DIV TWO",
        "style": {
          "flex-grow": "1",
          "display": "flex",
          "flex-direction": "column",
          "flex-wrap": "nowrap",
          "align-items": "center",
          "max-width": "310px",
          "min-width": "205px",
          "margin-top": "8px"
        }
      },
      {
        "elmType": "div",
        "_comment_": "DIV THREE",
        "style": {
          "flex-grow": "1",
          "display": "flex",
          "flex-direction": "column",
          "align-items": "center",
          "max-width": "310px",
          "min-width": "155px"
        }
      }
    ]
  }
}

Adding JSON to SharePoint

To change the formatting of the list we have to add the JSON to it

1. Click on the view
2. Select format current view
3. Paste the JSON in
4. Click save

Once you click save you’ll be able to see each row is now a grey box. You are looking at the main div here.

This is the end of part one. In part 2 we are going to add the column values of each list item into the view.

To recap:

• An overview was given on what JSON is and how it is used
• We planned how we wanted the list view to look
• We built the structure which will hold our column values from the list
• We styled it with CSS so it is ready for the values to be added into each child div in part 2