SharePoint, meet JavaScript: Solving long-standing challenges with new tools

Getting designers to play nicely with SharePoint, keeping clients happy on a short deadline, herding CSS !importants – what could possibly go wrong?

JavaScript to the rescue.

By Moti Zilberman, Lead Full-Stack Developer at Digital Detox In Journal, Dev

We were recently approached by a large client to work on a new generation of its Microsoft SharePoint-based product: a project management solution it had put together in house using a mix of off-the-shelf and custom-built components.

In the brief, the client asked us to identify and solve key usability issues with the existing solution and to develop a new look and feel layer for it while maintaining a single visual identity and coherent user experience across the two main solution components – Microsoft SharePoint and Microsoft Project, both web apps on the SharePoint platform. In the research we conducted, users repeatedly brought up navigation within the existing system as a major pain point, and we felt we could solve this as well.

Challenge one: the look and feel

With input from our design team, we first put together a SharePoint theme to use in both SharePoint and Project. This would apply the same colours and fonts throughout the solution.

It quickly became clear that we had to go beyond the SharePoint theme engine to satisfy our designers: the two products still had their separate logos displayed prominently in the page headers; we still wanted to improve layouts, spacing and form elements as well as add subtle touches like shadows and hover effects; and we found the theme engine itself limiting.

For example, setting a background colour in the header would also affect text colour in a separate side panel. Therefore, we turned to CSS. (If you come from a SharePoint background, you might ask why we didn’t just change the master page… we’ll let Vesa Juvonen, a Senior Program Manager at Microsoft, explain)

Writing custom CSS for SharePoint is something of an art. It is, in essence, retrofitting style rules onto existing markup developed over the years by several teams at Microsoft, all of which is internal to the SharePoint platform (so no official documentation) and some of which was not written with styling in mind. Needless to say, we spent a lot of time inspecting code in Chrome’s Developer Tools and working back towards reliable patterns.

An example of retrofitting style rules onto SharePoint markup

Finally, we brought in JavaScript and React: UI elements like the header and footer were best done in new markup, decoupled from the already-complex rendering code for the native elements. React provided a solid and testable rendering model for encapsulated components, which was especially valuable in a ‘messy environment’ where we controlled only a fraction of code on the page.

The default Project and SharePoint look and feel and a completely customised version

Challenge two: navigation

The disjointed out-of-the-box navigation systems of Project and SharePoint created significant user pain and reduced acceptance of the overall solution.

A view of the current system's navigation that reveal the workflow challenges

In our solution, we chose to hide all the existing navigation UI (using CSS) and insert custom JavaScript components (using React) to render a redesigned left-hand navigation bar, a contextual ‘back’ button and other related elements.

These components combine data from the SharePoint and Project APIs to create a unified navigation UI that looks and behaves exactly the same on both SharePoint and Project. It might have been easier to hard-code the new menu and be done with it, but we served the client better with a configurable and scalable solution, which could be easily adapted to different site structures, international markets and the like.

Wireframing sessions, the original SharePoint navigation and the customised version.

The workflow

Customising SharePoint has grown over the years into a noble tradition that comes with a lot of conventional wisdom attached to it. In this case, we deliberately chose to apply a modern web toolset to the problem. We wrote our code in ECMAScript 2017+ (with async/await and other goodies), compiled using Babel, bundled using Webpack, type checked using Flow, and unit tested using Jest. We used React for UI rendering, we wrote stylesheets as CSS Modules with SASS and PostCSS, and we regularly released semantically versioned packages (using Lerna) to our client via a private npm repository.

Even our build and deployment scripts (which we ended up delivering to the client, who found them useful in their own right) were command-line applications written in Node using the SharePoint Patterns & Practices JavaScript Core Library. This allowed us to use our JavaScript expertise to deliver a neatly packaged ‘one-click’ SharePoint deployment experience for the entire set of features we built.

Doing all of the above in a ‘brownfield’ project was not without its challenges. We still had to closely integrate with the client’s tech team who had their own process in place. Therefore we emphasised open communication, established a joint release cycle we were all comfortable with and provided clear and up-to-date documentation, which we wrote concurrently with the code.

The future

The SharePoint ecosystem is undergoing a sea change and JavaScript, a cornerstone of the web, is at the heart of it. Solutions that would once have required teams full of .NET specialists and a massive investment in server-side code are making way for modern, flexible client-side approaches involving standard web technologies.

Microsoft itself is in the process of rolling out the SharePoint Framework, a JavaScript toolchain with first-class support for creating SharePoint Pages and Web Parts in React. And it already provides increased support for SharePoint web development in the form of documentation and tools. Here at Digital Detox we’re excited to take on projects that form part of this technological shift, and are happy to share our experiences doing so.

Other blogs