Enhancement: `spo folder add` with option to set folder color

[milanholemans]

The idea is to add some options to set the color of a folder in SharePoint.

Commands to update

• spo folder add

Options to add

Option	Description
--color [color]	Visual color of the folder. Valid values are a color name or a number. Check remarks for more info.

Remarks:

When you specify a value for color, consider the following: Color	Number value	String value
Yellow	0	yellow
Dark red	1	darkRed
Dark orange	2	darkOrange
Dark green	3	darkGreen
Dark teal	4	darkTeal
Dark blue	5	darkBlue
Dark purple	6	darkPurple
Dark pink	7	darkPink
Grey	8	darkGrey
Light red	9	lightRed
Light orange	10	lightOrange
Light green	11	lightGreen
Light teal	12	lightTeal
Light blue	13	lightBlue
Light purple	14	lightPurple
Light pink	15	lightPink

Examples

Create a folder with a dark blue look

m365 spo folder add --webUrl https://contoso.sharepoint.com --parentFolder '/ProjectFiles' --name 'Project-x' --color 5

Create a folder with a light teal look

m365 spo folder add --webUrl https://contoso.sharepoint.com --url '/ProjectFiles/Project-x' --color lightTeal

Technical approach

Let's change the current API since it doesn't allow us to stamp the color of a folder. Changing to the API below doesn't change the output generated, so it's not a breaking change. Setting the folder color is easy, you just have to set the ColorHex field to a number between 0-15.

POST https://tenant.sharepoint.com/sites/MySite/_api/foldercoloring/createfolder(DecodedUrl='/sites/MySite/Projects/Project-x', overwrite=false)
{
  "coloringInformation": {
    "ColorHex": "3"
   }
}

Notice that this API only works when a color is specified. We could either stick with the old API when no color is specified, or we can just pass 0 with the new API to stamp the folder color "yellow".

[Adam-it]

good suggestion. Looks ok to me 👍 one question. Is the color now maybe present as part of the response from the API? if so we could also update the command output in the folder add docs

[milanholemans]

good suggestion. Looks ok to me 👍 one question. Is the color now maybe present as part of the response from the API? if so we could also update the command output in the folder add docs

Haven't played with it much yet, but as far as I know, this value is not included in the folder properties, so I don't think it's included in the response. I was thinking we should maybe somehow update spo folder get to return the folder color as well. But this means an extra API request.

[milanholemans]

Ok seems like I found a way to create a folder with a color in 1 API request, same with renaming a folder. I'll split this issue into two.

[Adam-it]

Ok seems like I found a way to create a folder with a color in 1 API request, same with renaming a folder. I'll split this issue into two.

good call. it will be easier to handle

[milanholemans]

Specs updated.

[Jwaegebaert]

Nice one, specs look clear to me!

[MathijsVerbeeck]

Can I work on this?

[milanholemans]

Thank you @MathijsVerbeeck