This example is now part of the repository OfficeDev Pattern & Practices available on GitHub:
Before starting, you will need to install some prerequisites:
- Install the SharePoint Online Client Components SDK. CSOM dlls are deployed in the GAC and used by theUtilityNavigation.ps1 script viaAdd-Type
- Install PnP PowerShell cmdlets for SharePoint Online v16
- Provision a site collection with the “Publishing site” template or with the publishing infrastructure features activated
Deployment and use
Simply follow the procedure on GitHub ? in theREADME.mdfile.
Once the solution is deployed in your site collection, here’s what you should see:
- A responsive navigation main menu wired to a taxonomy term set and using the Office UI Fabric CSS classes for rendering.
- A contextual menu and breadcrumb menu to insert directly in your pages.
Key points of this solution
Here is an overview of the solution. For more details, I tried as much as possible to comment directly in the source code:
- This is a generic and reusable solution that you can use with your own taxonomy term set.
- All CSS and menu behaviors come from the Office UI Fabric components. The navigation main menu is responsive by default.
- All navigation components are added via the Knockout JS ‘component’ binding mechanism
- All script dependencies are managed via Require JS, avoiding you to use the SP.SOD nightmare system.
- The deployment sequence is done via the PnP cmdlets and SharePoint CSOM
- The navigation menus support multiple languages.
- The default search box is integrated to the main menu navigation bar only by jQuery manipulations.
- The friendly URLs and simple links are supported as well as physical URLs (aspx).
- The source term set for the menu don’t have to be necessarily the term set used for the web navigation (for example in the case you only want simple links in your menu). However, to benefit of the friendly URLs, you can use directly the navigation term set configured for the navigation (like this example) OR a term set that reuses terms from it to get friendly URLs work.
- The browser local storage is used in this example to show how to cache the main menu navigation nodes. You can reset the cache just by adding a custom property directly on the term set (see instructions on GitHub).
- You may have noticed that the SharePoint default navigation system can have some limitations. Among them, the impossibility of separating data sources by navigation menus, SharePoint limiting you to the global and current navigation (so no footer, header, etc.). With this approach, it is now possible to create as many navigation menus as desired on a page.
- And finally, it’s an open source solution, so feel free to use it and improve it!
Styles and component behavior management
Why Office UI Fabric?
Office UI Fabric is a toolbox of reusable components and graphic styles for Office and Office 365. Its use allows your applications to adopt the same standards and components as the original platform, without having to manage styles and behaviors. If like me, CSS is clearly not your strength and you want to seamlessly integrate your applications very quickly with the rest of the platform, Office UI Fabric is made for you! You just have to use the bricks that suit you.
The official website is available here: http://dev.office.com/fabric.
Note that the project is primarily maintained by Microsoft designers and by the community. The GitHub project is available at: https://github.com/OfficeDev/Office-UI-Fabric.
In this example, we use the main navigation menu available in the list of components of Office UI Fabric:
The advantage of these components is that they are, for the most part, “responsive” by default. It means that you do not have to integrate third-party frameworks (such as “Bootstrap”) to manage the mobile display. Reduced to a SharePoint Online context, it means that you do not have to change the master page.
Also note that there is a grid system available in the tool (like Bootstrap).
Component’s dynamic inclusion
To address this problem, I use the “component” binding technique of the Knockout JS library. This mechanism allows to inject dynamically the HTML structure of a component directly from a separate file.
For example, to insert the navigation menu on a pages, you just have to include the following line, and then to callko.applyBindings()only on this item to get the HTML structure of the component automatically inserted in the page. This technique provides similar behavior to “delegate controls ” and greatly enhances the code readability.
Quite honestly, I’ve never been a big fan of the “Script On Demand” mechanism (SOD) offered by SharePoint by default, finding its syntax too “heavy”. In a context where updating the master page is no longer possible, which is becoming the standard with SharePoint Online (otherwise, it is possible to get out via the<SharePoint: ScriptLink />), it is not uncommon to have to do this kind of thing (taken from the example of PnP navigation menu): several nested calls to ensure the loading sequence.
From the SOD syntax seen previously, we get the following equivalent with Require JS:
With this configuration, we ensure to have all the dependencies loaded when executing code in the taxonomy module:
Another benefit is that Require JS modules are resolved relatively from a main script. Simply include only one script in the page so that all dependencies will be automatically resolved relatively to the main script according to the folder hierarchy in the style library of the SharePoint site:
Deployment of the solution
The solution is deployed by PowerShell, both PnP via cmdlets (Pattern & Practices), and also by CSOM code.
- All * .js scripts and * .html files are deployed to the root site of the site collection, in the style library, via theAdd-SPOFileorder. The advantage of this command is that it automatically creates the folder hierarchy if it does not already exist. Also use the “-Checkout” parameter … to archive the file after adding. Notice that for better performances, don’t use the style library to store files, prefer a CDN instead.
- Only Office UI Fabric CSS are loaded from an external URL.
- It is not possible to mix PnP cmdlets and CSOM code. For example, if you use the result of theGet-SPOContextcmdlet to get a SharePoint context and pass it to a CSOM method, it will not work (you will have an error of object casting).
- When using SharePoint CSOM, prefer to load the assemblies from the GAC via theAdd-Typecommand (you must specify the FQDN of the assembly). Remember, these are installed via the SDK SharePoint Online Client Components.
About the Author:
Working as a SharePoint specialist for 5 years now, I’m very specialized in intranet and portal solutions with this platform. My day-to-day role is to design and build solutions that meet expectations while leveraging the maximum possibilities of the platform. I’m also very concerned by agile methodologies especially Scrum to understand and organize requirements before and during the implementation.Through my speeches and articles, I want to share my knowledge according to my reality on the ground. Franck has been a Microsoft MVP for Office Servers and Services since 2016.
Follow Franck on Twitter: @