Graffiti guidance

Advice on using unsupported customisations (and more) in a SharePoint Online environment

Photo by Richard Sandler of 1980’s New York

The other week I was watching Vesa Juvonen and Stefan Bauer discuss the new 3M intranet that was built on top of Office 365 SharePoint. As they walk through the details of the screenshot of the intranet, they notice some elements and changes in the UI that could never have been accomplished without ‘colouring outside the lines’. The discussion then evolves into a little debate whether DOM injection or CSS injection was applied and if this should be a recommended approach in the first place.

Since I’ve had a lot of discussions about similar topics with the team I work with at my current project, I thought it would be nice to share my thoughts and conclusions.

The topic of using unsupported manners to achieve a certain goal in Office 365 (SharePoint Online) has been discussed by other people before me, but I hope my article adds something to the discussion by:

• introducing a new term for these manners
• distinguishing the various types of unsupported modifications
• explaining some of the risks

and

• providing some guidance on how to proceed

Why ‘graffiti’?

When we first started talking about these injections/unsupported modifications we called them ‘hacks’. Using a term like that frequently in an environment that has digital security high on the agenda didn’t really work well so we needed a more friendly term. Also, since I included DOM and URL dependencies to the scope as well (read more about this in Definition and scope of graffiti later on in this article), the term ‘hack’ didn’t really cover it anyway.

The idea to use graffiti as an analogy for these unsupported modifications/dependencies came to me when I recalled reading a chapter in Freakonomics about the decline of criminality in New York in the 1990’s. It mentioned the “broken window theory”, a theory in which it is thought that when one broken window is left unfixed, it sends a signal that it’s ok to break other windows as well (and maybe even set the building afire too). The same goes for graffiti: as soon as someone paints a tag on a clean wall and this isn’t cleaned quickly, more and more of these tags will follow and soon you can’t even tell what colour the wall originally was.

graffiti
/ɡrəˈfiːti/

noun
writing or drawings scribbled, scratched, or sprayed illicitly on a wall or other surface in a public place.

In the early stages of designing the new intranet for our customer, I sensed something similar was happening in our team. Quite often the question arose whether we could develop/build/manipulate something when the solution wasn’t so obvious. In many cases it couldn’t be achieved using supported methods so we had to fall back to more questionable ways of accomplishing the goal. In a matter of weeks we discussed probably close to 10 different (parts of) solutions that required either unsupported DOM/CSS modifications or dependencies ranging from hiding certain parts in the UI to moving things to other areas. Even though some of us had a gut feeling that maybe we should be more hesitant in choosing this course, the idea that “since we already agreed in doing it there, we might as well do it here” prevailed.

I felt it was time to start a team-wide discussion about the possible consequences of our decisions and put together a small PowerPoint presentation to outline various aspects and provide strict guidance on how to proceed. This article is an extended version of that presentation.

Definition and scope of graffiti

Let’s start first by defining what this ‘graffiti’ comprises. I tried to sum it up in the following definition:

SharePoint Online graffiti are unsupported (by Microsoft) functional or visual modifications to or dependencies of the out-of-the-box SharePoint Online product.

I’d like to make a distinction between the following types of graffiti. Not every type has the same risks and impact and I think it’s good to know the differences.

1. DOM Injection, DOM Modification
   These are probably the most common types of graffiti. Think of adding, moving or hiding a menu item, change the handling of a default button or inject something completely new, like a sidebar with new ways to navigate. The risk of breaking something is the highest in this category, since you change something in the core (DOM) structure of SharePoint.
2. CSS Injection
   Most of the time this actually involves some DOM injection since you’d probably add custom CSS by adding a style-element to the head of the DOM. Once successfully injected, with CSS you could change the appearance of almost everything by overriding the default styles that Microsoft provides. You could hide elements, change their size or colour, modify the way they’re positioned and so on. The risk of breaking something is slightly less apparent as with DOM injection, although you could unintentionally hide something that’s required for proper functioning of the core product.
3. DOM Dependency
   One might question whether this really is graffiti, but I think it deserves to be mentioned as a separate category. The idea here is that you don’t manipulate any existing element, but instead depend on the existence and behaviour of it. An example of this could be an SPFx web part that mimics the behaviour of the out-of-the-box submit-button by copying the DOM element for the button and putting it inside the web part. Another example is an extension that monitors whether the (default) Page Details side pane is open and when something changes in that state, shows some message in the header.
   You won’t break the SharePoint experience with these components, but chances are that when MS decides to update the DOM structure, your component will no longer work as designed.
4. URL Dependency
   This one is similar to the DOM Dependency but in this case you depend on the presence (or absence) of a certain part in the URL. A good example is provided by Elio Struyf in his article about detecting the page mode from within an SPFx Extension. He offers a solution to detect whether a modern page is in ‘edit mode’ by observing the current URL for the existence of the query string “Mode=Edit”. If Microsoft ever decides to change something to this (i.e. change the syntax, or remove it from the URL and keep track of state in a hidden form field) your solution will break.
5. Other?
   There might be more types of graffiti. I haven’t seen examples of this yet, but maybe there are ways to completely override specific Javascript-methods (like we did back in the day) so that could be another category.

So what are the risks?

When choosing the ‘path of the unsupported solutions’, there are many things that could go wrong. The impact if something does go wrong varies greatly.

Following are some of the risks to consider when choosing to ‘apply graffiti’ in your project:

1. Your graffiti could potentially break SharePoint.
   This is probably the risk with the highest impact. If your solution does DOM/CSS injection or modifies the out-of-the-box product in any other way, you probably do this by “assuming” a certain DOM structure at this moment, and by applying your modification based on this assumed structure. For instance, you might want to hide a certain element in a menu, and you ‘find’ this DOM element by using a CSS selector of some kind. If your selector is rather ambiguous (e.g. select the 3rd child node of node with class x) it might be that when you built your solution it did exactly what you intended it to do. But as soon as Microsoft changes anything in their DOM structure, it might be that your selector no longer selects the intended element, but some other element or group of elements. In this case, you might unintentionally hide elements that are required by SharePoint to function properly.
   Admittedly, you won’t break SharePoint in a way that would have Microsoft call you to please take offline your solution because you’re talking down their servers. However, you could surely break the experience for the users of your tenant!
   If this happens, you should probably fix the CSS selector accordingly and upgrade your solution quickly, but if you’ve got rather bureaucratic release procedures this might take a while to bring into production. In the meantime you could either accept that SharePoint doesn’t function completely or decide to deactivate your solution temporarily. None of these scenario’s probably help in achieving user satisfaction.
2. Your customisation/solution no longer works (completely) as designed.
   The impact of this highly depends on the business value of your solution in the first place and the level of malfunction. You might have built the #1 ‘silver bullet’ solution that drives your customer’s business completely in which case the impact could be severe. On the other hand, if your solution merely comprises moving an element 10px to the left because ‘it just looks better’, the impact of not finding that DOM element because Microsoft decided to change the class name would be negligible.
3. ‘Sorry, we can’t help you’
   If you ‘crossed the line’ and chose to allow graffiti in your environment, chances are that Microsoft won’t offer support when you need help with troubles in your intranet. They probably want you to take offline all your custom solutions that contain unsupported elements to make sure the issue isn’t caused by it.
4. An audit could damage confidence in your abilities
   If you’re working for a big company, chances are that company might one day ask one of your competitors to do an audit of your work. If you’ve got graffiti all over your solutions that your customer doesn’t know of (or approved of), discovery might have impact on your relationship.

In my current project we’ve already come across cases where a certain solution worked fine at one point during development, and within a month it stopped working because Microsoft made changes in either a classname or something else in the DOM structure. I’ve heard of other cases where this happened, so these risks are really something to take into consideration.

So should we even consider this?

Now that you know the risks, why would you consider using graffiti in your solution and not just stick to the ways Microsoft does allow you to ‘extend’ the product?

Well, in general, I think that should indeed be the approach. After discussing the risks with the team and, more importantly the customer, in many cases the need for a specific solution isn’t even as big as it was stated initially. You might be able to alter your solution a bit and still meet the requirements, or maybe Microsoft makes an announcement that a certain change to the product is imminent that comes very close to what you had in mind and no graffiti is needed to accomplish something similar.

But there could still be scenarios where you’ve thought well of a solution and require some form of graffiti to build it. There might be no other way to solve it and since SharePoint covers your customer’s needs for the other 95% it would be a shame not to go the extra mile and make it a complete match by doing that tiny bit of unsupported customisation.

If you’ve arrived at this point in a project, be cautious and follow these rules to minimise risks and prepare well for the day your solution might break:

1. Inform your customer of the risks. Put it in writing if necessary to cover your behind in case something does go wrong.
2. Be meticulous. This is especially important in cases where you want to alter some element or collection of elements by selecting them using classnames, id’s or tag names (using jQuery for instance). The more specific you make your selector, the lower the risk of selecting the wrong elements and potentially break something.
3. Verify your assumption. This is also to mitigate the risk of applying your graffiti to the wrong element and cause unexpected results. I.e., if you expect your selector to come up with one element, verify this is the case before applying your customisation. If your selector returns unexpected elements, cancel the operation (and use some sort of logging to make sure the dev team knows of the issue asap).
4. Maintain a list of all the graffiti that’s in production. In this list (it could be a SharePoint list or a wiki or whatever you prefer), write down the following details about your ‘cases of graffiti’:
   - Title (to easily find later it in the list, for instance ‘Preventing deletion of web parts by hiding the delete button’)
   - Type (like DOM Modification, or URL Dependency)
   - Description (how does your graffiti work and what is it composed of, maybe provide a link to an article you found online that gave you the idea)
   - Product/Repo (to make sure you can find the source code of the product in case you should change anything)
   - Production Url (a url to a site or page where the product is ‘live’, to check regularly if everything is still working fine)
   - EOL (End-Of-Life) Criteria (since you probably want to get rid of the graffiti as soon as possible, write down the criteria for when this is possible. For instance, if you built an extension to check if all required fields in a modern page have proper values and you prevent a page from publication using some graffiti, write down that as soon as MS implements something similar out of the box there’s no longer a need for this extension)

As long as you use it scarcely and follow these tips, graffiti could quite safely be used in your solutions and help you in your quest to reach 100% customer satisfaction.