2019-04-02

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
}

You can see that the pairs are placed inside curly brackets { }. After each entry, there is a comma apart from the last line to specify a new line.

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.

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.

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

a An <a> tag element defines a hyperlink, the <href> attribute accompanies an <a> tag as that points to the URL destination you specify
button The <button> element is used to create a clickable button from text/icons etc.
div This is a container that encapsulates elements. You can have multiple divs to separate elements from one another, you can also nest divs inside divs
img The <img> tag creates a holding space for a referenced image, you reference an image with the <src> attribute
path This is another <SVG> element, it is used to define a path of the graphic (not to be confused with link/file paths)
span The <span> tag is used for housing elements, for example, you would place a list item value that is text in a span, inside a div
svg <SVG> stands for Scalable Vector Graphics. The element type creates a holding space for the SVG

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
(Visited 14,640 times, 79 visits today)

About the author 

Jamie Bray

Office 365 Collaboration Specialist at Parliamentary Digital Service

Leave a Reply

  1. Hello.
    This article is very useful, thanks.
    I have one issue, maybe you could help.
    I have made a formatting to a sharepoint library.
    It works but also for subfolders… what I do not want.
    Can I apply a formatting just to one library level (upper one) ?
    Thank you

  2. Hi I am trying to have a read more option like i want to show two like then a read more option people clicks on it and it expand to show the more data is it possible in the JSON formation of a column

  3. Hello,

    If I only want my image column to be bigger, how can I do that? I have a custom list with multiple columns but I only want the image to be bigger.

    Also, I followed part two, but my images didn’t show anymore after I saved it.

{"email":"Email address invalid","url":"Website address invalid","required":"Required field missing"}

2 Free Ebooks: How to govern Microsoft teams 

Download your 2 free Microsoft Teams governance Ebooks and learn the steps necessary to create a bullet-proof governance strategy.