When I looked at the repository of my SimpleStyle Guide, I couldn’t believe that it was almost two years ago when I started this side project. Which those two years this Style Guide helped me in many projects to document all the changes in classic as well on the modern experience in SharePoint and Office 365.
At the last European SharePoint Conference, I got a great question during my workshop from someone attending: “Will there be a new version of the Style Guide?” Two things to note here. I haven’t expected that someone uses it except me. The second thing is, that there is a demand for this, especially when it comes to migration to the modern experience. So here it is an entirely rewritten new version of the SimpleStyle Guide, and the changed I did.
SimpleStyle Guide version v0.4.0
No more jQuery
There is one crux issue with jQuery, React, Angular; you name it. What if I want to combine it with other libraries and tools. The version of 0.3.0 makes heavy use of jQuery. In case you needed to have different jQuery library than I used you might run into trouble and therefore were not able to use it.
As a matter of that, I completely re-wrote the whole user interface without jQuery and without any other library given you the opportunity to choose whatever you like.
If you like to use jQuery just add it to your instance of the style guide and you are ready to go. The only exception is HandlebarJS to render the pattern on the user interface but this small, working and old add-on is blazing fast.
TypeScript Support included
To build the code for the user interface I used TypeScript. Not because I wanted to have rock solid types implemented. Most of them are anyway standard types, such as HTMLElement and so on. Anyway, you even can use plain old JavaScript still.
The reason for that was a bit different. I used TypeScript because I don’t want to rewrite the JavaScript code again, when I switch from ES5 (ECMA Script 5 – currently used for the user interface to a newer version. In case of TypeScript, I will be merely able to recompile.
Improved Session and State handling
Just because I don’t use any of the fancy frameworks, I’m now able to provide session and state handling. For example, you were working on a card layout and needed to take a break and shut down the SimpleStyle Guide; you are able now to start again with the same filter you finished your last session. Made possible through the use of localStoragewhich is widely supported by all major browsers now.
It was the tricky part, but the work was worth it.
MarkDown Documentation
The file pattern.conf.json in the app directory stores all the information about the patterns included in the style guide.
{
"patterns": [
{
"title": "01-atom",
"description": "",
"filename": "01-atom",
"filepath": "atoms/01-atom.hbs"
},
...
In the old version, you were able to add a description to your patterns by manually add the description field in this JSON file. It is still possible but there is also a new folder named _documentation, and this folder can store MarkDown files. The structure there needs to be matching to the _patterns folder.
Pattern 01-atoms.hbs and corresponding MarkDown file 01-atom.md
For example, you have a pattern stored under app/_patterns/atoms/01-atom.hbs and have a MarkDown documentation of this pattern stored under app/_documentation/atoms/01-atom.md the pattern and the MarkDown file will be merged. If no markdown file exists, the documentation will be taken from the description filed defined in the configuration. This new method gives you even the possibility to add source code to your documentation like this.
Source Code Documentation in SimpleStyle Guide
Office UI Fabric, Bootstrap whatever you need
If you make use of Office UI Fabric, Bootstrap or any other front-end framework just added it via Yarn or Npm and reference it in the index.html file. Currently, there is no official documentation on that available, but I’m looking forward if need to document this as well.
Angular 1.x, Angular Elements, VueJS, …
The fact that I re-wrote the complete style guide from scratch without the use of any framework you can even embed things like Angular or Vue. Currently, I ran some tests on Angular, and it looked promising and was able to get things from ngOfficeUIFabricrunning in the style guide. The key for angular is using the Bootstrap method (Not the UI Framework in this case). The following code demonstrates how to force angular to init after the Style Guide completed rendering.
/* Bootstrap for Angular */
var test = () => {
// angular.bootstrap(document, ['ng-ssg']);
angular.element(function () {
console.log('Running');
angular.bootstrap(document, ['ngSsgApp']);
});
}
/* Push it ot Style Guide UI */
ssg.UI.PostRender.push(test);
Similar to the jQuery directive on document ready you can push functions to sag.UI.PostRender that will be executed right after the Style Guide completed rendering.
ngOfficeUIFabric embedded in SimpleStyle Guide
One word of ReactJS. No secret here that I’m not a big fan of it but I admit it is pretty fast to develop components and it is all JavasScript without any real dependence on web technologies. The fact that I was not able to run ReactJS without WebPack or Browserify makes it hard to include it in this or any other HTML/CSS based style guide. Anyway, the components and style sheets used and documented in this style guide can be used to build ReactJS components too. I also think if you have proper documentation on the HTML and CSS side you will be able to convert it to any other framework easily. Event web designer without explicit JavaScript Framework knowledge should be able to build significant components. If someone comes up with a smart way to integrate it, please let me know.
Sample Data and Data Binding
Sadly the patterns used in the old style guide were pretty much static HTML code without any chance to have custom data binding. Something that has changed in this release too. Inside the _data folder there is a small tiny JavaScript location that can store whatever data you like to use.
var ssgData = {
href: "?",
title: "Hello World",
navigation: [{
href: "?",
title: "Title"
}]
}
Simply add properties in this variable ssgDatavariable and use them in the templates to generate links.
<a href="{{ href }}" title="{{ title }}">{{ title }}</a>
Simple reference any property in the ssgData object in your template and encapsulate the property name in curly braces. The output in the style guide then should be a hyperlink.
Data Binding in SimpleStyle Guide
So you merely bind now any data to any pattern. This functionality is brought to you by some backend code on my side and the methods provided by HandlebarsJS or check out the documentation I provided.
Just some last requests
To be honest, it was a hell lot of work, but it was worth it. If you use it, like it misses a feature or needs some, just let me know. Move over to the GitHub project and Star the project. If you have any feature request or problem, please open an issue. There is some documentation upcoming and missing from my side, but after one year changing piece by piece, I must admit I am now a little bit blind to the small details. I also plan to have sample documentation of all Office UI Fabric components, that can be included in the SimpleStyle Guide and many more ideas to come. This an open source community project and I’d like to help anyone get their things done easier and better documented for upcoming SharePoint and SPFx project. Oh, one thing I nearly forgot.
npm version minor & npm publish
The new generator is now available.
Further Links
Photo by Markus Spiske