I've been wanting to write this post for a long time. Back when the Office UI Fabric was released, I was instantly pushing for a set of Angular 1.x directives. Microsoft didn't have it in their plans so I kicked off a community open source project: ngOfficeUiFabric.
Over the last few months we've setup a nice build process and had six different people contribute directives to the library! We've published version 0.1.3 of the library which includes a few directives:
<uif-textfield /> &
What is ngOfficeUiFabric?
This is a collection of directives that implement the Office UI Fabric components with no script dependencies except for Angular. The aim is to make it easier to use the components in fabric within Angular applications.
You don't have to know all the CSS classes that Fabric uses or exactly how the HTML should line up, the directives do that for you. In addition, because it's more than just CSS, we will have useful functionality in our directives. For instance, ultimately the table will provide sortable columns!
There are other design libraries out there you can use to build your Angular applications for Office products, such as Angular Material and UI Bootstrap which are fantastic options, but why not use the same design language that the hosting application (Office clients / Office 365 / SharePoint) uses?
What is in the v0.1.3 Release?
Not a ton of stuff... we're just getting started. In the last few weeks we've had a lot of momentum from folks in the community jumping into the project. So right now, we have a total of four directives:
<uif-contextual-menu />: Implementation of the contextualmenu ;by @s-KaiNet
<uif-dropdown />: Implementation of the dropdown component; by @rolandoldengarm
<uif-icon />: Not an official Office UI Fabric component, but it simplifies working with icons; by @andrewconnell.
<uif-searchbox />: Implementation of the searchbox component; by @jigargandhi
<uif-spinner />: Implementation of the spinner component by @jjczopek.
<uif-table />: Implementation of the table component by @waldekmastykarz.
<uif-textfield />: Implementation of the textfield component by @rolandoldengarm.
<uif-toggle />: Implementation of the toggle component by @rolandoldengarm.
How Can I See Them in Action?
We have plans for a full-blown demo site in the future, but the idea was to get a handful of directives built first so we have something to work with. That demo site will live at http://ngOfficeUiFabric.com. Today each directive in the main source repo contains a few usage demos where you can see how they work. I took these demos and put them in a spot where you can easily see them working without any extra work. For now if you go to http://ngOfficeUiFabric.com/demos you can see each directive in action.
However you can also build the library yourself. Jump to the section on How Can I Get Involved below to see how this is done.
This has been a collaborative effort, a classic open source software project, among a handful of people in the community who have volunteered their time and skills. Today, other than me, we've had these fantastic contributors:
- Jigar Gandhi (@jigargandhi)
- Jerzy Czopek (@jjczopek)
- Roland Oldengarm (@rolandoldengarm)
- Sergei Sergeev (@s-kainet)
- Waldek Mastykarz (@waldekmastykarz)
Today's release v0.1.3 includes a handful of directives. We have adopted the symver for versioning. When we have new directives to add, we'll increment the minor version (v#.this.#). Fixes / patches will increment the patch version (v#.#.this). Once we have a feature-complete library which has directives for all the components in the Office UI Fabric, we'll issue our v1.0.0 release.
How Can I Get Involved?
Interested in picking up a directive and contributing? Fantastic! First, I'd get a copy of the project locally, build & test it. Poke around and see if things are familiar to you to see how we do things.
For the geeky / code questions, here's a high-level overview of the project:
- We are using the external module pattern in TypeScript to define the directives (no namespaces / internal modules).
- All code is vetted against defined rules using TSLINT.
- Module loading in the browser by employing webpack which does all bundling & dependency loading of the modules. There's nothing for developers to do here... everything is already setup. If you need a module, you simply import it into your existing module and webpack handles loading it for you.
- All directives must have associated unit tests and a high level of code coverage (today over 99% of all lines are tested).
- When pull requests are submitted we have an automated build process that kicks off via TravisCI that builds the library, runs all tests & other checks. If something fails, it's on the developer who's submitting the pull request to fix it before we consider it.
- Eventually we'll have an automated release process where each time someone adds a new directive, we'll increment automatically build a new version & publish a release.
Minimal Path to Awesome
Want to see it in action? We have a Minimal Path to Awesome doc that walks you through getting the code, installing the dependencies (there are only two: TypeScript & TSD) transpiling the code, vetting all the code for style conformity, run all unit tests, view the code coverage reports, building the library & viewing the working demos... all from the source code in the main repo.
Feeling adventurous? Give it a shot!
Interested in helping out? Check out the CONTRIBUTING guide to see our guidelines then check out our issues list to see what directives haven't been claimed and express interest in one!