Configure column and view formatting using the Office 365 CLI

Using the latest version of the Office 365 CLI, you can easily configure view and column formatting in your SharePoint sites.

Column and view formatting

Column and view formatters are a light-weight way of changing how the information stored in SharePoint is presented. Whereas the SharePoint Framework Field Customizers require custom development an admin deployment, column and view formatters can be done by users directly through the SharePoint UI, allowing them to tailor SharePoint to their needs without costly projects and cumbersome approvals.

SharePoint list columns formatted using a column formatter

Configure column and view formatting using the Office 365 CLI

Starting from the v1.10.0 beta, you can use the Office 365 CLI, to configure column and view formatting in your SharePoint sites in a structured and repeatable way.

To configure formatting of your column, all you need is its location and the JSON string of the column formatter:

spo field set --webUrl https://contoso.sharepoint.com/sites/project-x --listTitle 'My list' --name 'My column' --ColumnFormatter '`{"schema":"https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json", "elmType": "div", "txtContent": "@currentField"}`'

In a similar way, you can configure view formatting of your list:

spo list view set --webUrl https://contoso.sharepoint.com/sites/project-x --listTitle 'My List' --viewTitle 'All items' --CustomFormatter '`{"schema":"https://developer.microsoft.com/json-schemas/sp/view-formatting.schema.json","additionalRowClass": "=if([$DueDate] <= @now, 'sp-field-severity--severeWarning', '')"}`'

While using both commands is pretty self-explanatory, there are some additional considerations that you have to take into account, when using them in Bash.

Configure column and view formatting in Bash

Despite column and view formatting being relatively easy to use, you can use them to build pretty advanced solutions. The JSON strings describing formatting of the data will then get pretty long. For practical reasons, you will likely manage them separately from your scripts used to apply them to your SharePoint sites. And if you happen to use Bash or a similar shell, here is where problems arise.

Single-line arguments

Bash commands don't accept multi-line argument values. This is problematic, if you want to pass a few hundred-lines long JSON string to the Office 365 CLI. Before you do, you first need to put the long JSON string in one line by removing all line breaks. In Bash, if the string was short, you could've used something like echo "${1/[$\\r\\n]/}". Unfortunately, if the string gets just a bit longer, executing this commands takes a long time.

A better alternative is to use jq, which, if you're using Bash regularly, you will likely already have on your machine. Using jq, you can easily, but also very quickly, reformat a JSON string into a single line by using cat "$jsonDefinitionFile" | jq -c '.'.

Passing JSON strings as command arguments

Once you have the JSON string reformatted into a single-line string, the next challenge is to pass it as the value of a Bash command argument. A JSON string will likely contain double quotes and spaces, and sometimes also single quotes. So you can't just pass it as-is as a command argument. Instead, you have to wrap it in just the right pair of quotes which happens to be '`'"$json"'`'.

The double quotes are required for the command to pass the value of the json variable rather than its name. The backticks are required, because the JSON string contains double and single quotes which should be passed to the command without processing. And to include the backticks in the passed string, you need to wrap them into single quotes.

Putting it all together, following is a Bash script that configures column formatting based on a JSON string stored in a separate file:

#!/usr/bin/env bash

siteUrl=https://contoso.sharepoint.com/sites/project-x
listName='Task List'
listColumn='Task Status'
jsonDefinitionFile="TaskStatus.json"
# get file contents and print as a single line
json=$(cat "$jsonDefinitionFile" | jq -c '.')
echo "Configuring column formatting..."
# update field. notice the special way of escaping the JSON string in CustomFormatter
o365 spo field set --webUrl "$siteUrl" --listTitle "$listName" --name "$listColumn" --CustomFormatter '`'"$json"'`' --verbose

Before you run the script, don't forget to login to your SharePoint tenant.

Summary

Column and view formatting allows you to control how information is presented in your SharePoint sites, without building packaged solutions. Using the latest version of the Office 365 CLI, you can configure column and view formatting programmatically. If you want to automate configuring formatting using Bash scripts, there are some additional considerations required for correctly processing the JSON strings that described the formatting.

Comments

comments powered by Disqus