Microsoft 365 Community Community Demos, 12 Jan 2023

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Getting started with hTWOo React controls for Microsoft 365

Description

What is the hTWOo UI library (hTWOo – Core, – React, – Icons)? In this 19-minute developer-focused demo, permit Julie Turner to take you through the installation and creation of an SPFx solution using hTWOo assets. See setting up theme support, initializing icons, creating a class/function component, and importing hTOWo assets into an SPFx project. Extensibility is built in at the core. Uses Atomic Design to organize components. Components minimize bundle sizing. Teams theming for use in SPFx Teams solutions.

This PnP Community demo is taken from the Viva Connections & SharePoint Framework Bi-weekly sync call recorded on January 12, 2023.

Demo Presenter
📺 Julie Turner (Sympraxis) | @jfj1997

Supporting materials
• Site - hTWOo Design Studio | https://lab.n8d.studio/htwoo/
• Repo - HTWOO UI framework | https://github.com/n8design/htwoo

Learn more
• Microsoft 365 Unified Sample gallery - https://aka.ms/m365/samples
• Microsoft 365 Platform Community in YouTube - https://aka.ms/m365/videos
• Microsoft 365 Platform Community - http://aka.ms/m365/community

👋 Join to our weekly Microsoft 365 & Power Platform Community calls to learn more. These are PUBLIC calls for you to get access on the latest details from Microsoft and to see awesome demos from community on these technologies - Download recurrent invites from https://aka.ms/community/calls

A

A

So um my name is Julie: Turner I am with some Praxis Consulting and today I am going to give you a overview and some demo on the H2O react component library, and so this library is a collaboration between myself and Stefan Bauer of NAD design, and so uh let me just quickly give you a little visualization of who I am but we're going to move really quickly because that's not very important all right. So what is H2O H2O is an open source alternative to Microsoft's, fluent UI web design system um at its core.

A

So there's an a a piece of this called H2O core, which is a style guide based on HTML and CSS, to create the implementations for then any framework. Unlike um the fluent UI web system that is available, that's only react controls. This is an HTML and CSS based Library, so that you can use that design language in any framework. In addition to that, we have built a react library of those controls and that's what I'm going to show you today. So how do we get started?

A

We get started by creating your SharePoint framework solution uh using react.js. You can also build an external react.js application and use this these components in that as well. You would then install H2O react and you do that by just an npmi install of the H2O react. Library, you set up theme support you initialize icons.

A

You then create your class or function component, and then you import the H2O react component that you need one of the main features of the react component library is we try to build extensibility in at the core, so every component has a sort of template or style to it that that extensibility right at its core, and so, if you uh look at the little image I have here on the screen. uh The item marked with a red too the interface.

A

The props interface for every single component in our library contains an element at least one called root element attributes. And what that is, is it's an HTML? It's a typed HTML attributes list, for whatever the root element is of the component Now by default. That's HTML element, so it's a a a generic element, but for each one, when we Implement them, we change out HTML element to whatever that root element is all in the render method.

A

So, if you were to see online 35, this is a the root element of this component is a div element, so we would change that root element, attributes to the attributes for an HTML div element and what that gives you is a way to do any add any attribute. That is an HTML attribute of a div element to this control.

A

So if you need to add, drag and drop events, if you need to add custom styling, if you want to add extra classes, any attribute of an HTML development, you can add by simply adding them into the properties of the component as well.

A

All of our components do logging to the console, and we do so by if you look at line 20 there by having a customized um logging source that has an icon in it and what that helps you do is be able to see where anywhere in your console, that you have that little water symbol in the beginning of the name of the control, you can quickly find any issues that are arising because of these components.

A

Okay, so that's the overview, and now let me just dive right into the demo. So let me get out of of the slides and we're going to come back over here, and so we have is the landing page I just wanted to show it the landing page for the uh H2O site. So, as I mentioned, we have H2O core, we have H2O react. So core is the HTML and CSS straight up. You can use that and there is a um there is documentation on how to get started with core, so that will help you.

A

Then we have the documentation and all the information for our H2O react. We're going to dive into that. We also have another Library called H2O icons. These are all 3 200 office, fluent UI um icons, uh converted to SVG icons, so I'm going to show you a little bit more about that as well all right, so let me get out of the lead documentation. This is the landing page for the H2O, react components and so right off.

A

We start with a getting started page and this walks you, through step by step so essentially you're going to install H2O react. The library has a dependency on H2O core and that gets installed for you as a dependency. So you don't have to worry about that part of it. The next step we're going to do is we're going to import the core Styles. So all those styles that HTML and CSS live in that core library and we need to add an import to get those Styles into our solution.

A

So the way we do that is, we go into our root uh web uh web part scss file and we add a global decorator to our import and I'm going to show you this live uh and then we have, to you know, add an in import into our root react element to put the class name as the Styles dot my root webpart. So that's this class name, that's in our scss file. We need to import that into the root div of our entire react project and the reason that we do.

A

That is because that adds the CSS variables to that root component, so that all the variables that are needed for the theming support and everything else are there for the components so that they style properly and then, last but not least, a new newly implemented in the SharePoint framework.

A

1.16 is a feature in the config file in the config directory folder there's a sas.json file and we need to include this quiet depths equal true and it's a long story on why that's necessary, but essentially it's to uh quiet warnings about the version of SAS that we're using. So we will go through that in um we, so we won't go into that any more detail.

A

um The last thing that we have to do to get working is in initialize the base, SVG icons that are used by the library itself, so for like the drop down, control and uh other things like that, where we have uh some icons built in those are built into the library and we need to initialize those so we're going to add uh a import for a for a class called that has a default Global called simset, we um that's short for symbol set class and we await symbol, set dot, init symbols which sets up the icons that are by default, needed for all the controls and we'll go I'm going to go into a little bit more about that uh shortly.

A

And so let me just say that if you want to create a set of icons that you can then use for uh in your control, controls like you want some buttons or you have other places where you inputs or any other thing where you want to have some iconography.

A

You can also use this new tool that Stefan built called the icon tool, and so this is a listing, it's very similar to Chris Kent's flycon. It's a listing of all the icons that are available and what you basically can do is go through and pick the icons that are ones that you want to include in your project and once you've picked all the ones that you want.

A

You can click this download button and it gives you an SVG symbol, set file that you can then add to the assets of your project and then import that into your solution, and so how you would do that is you'd get that symbol set file added into like your assets or somewhere else, and then you import that symbol set file. After you add at the root Source an image.d.ts, it could actually be anything.

A

It doesn't have to be images but something dot: d, dot, TS file and in that file we're going to declare svg's files as a content type so that the import will know what it is so I'm going to say, import simple, set file from that SVG and then, instead of not passing anything when I init symbols I'm going to pass in the name of that symbol set file, and so that would then add those icons and then I can reference them when I'm using icons in my work other than that, we can also just include the H2O icons library and then pick out the entire SVG, all 3200 icons and pass those in and initialize those.

A

So that's another way to do it. Another thing we do is support theming. So if you're in SharePoint framework I have created a class called the spfx themes class- and it takes all of that boilerplate code that you need for theming support and consolidates it so that you only really need a couple lines of code to add theming support and it really does clean up your base class. So we need to to use that we need to import themes, provider and that's an SP component object.

A

We also need to import that spfx themes class in the interface. So then we create a private variable for the the theme and create an instance of it, and then we want to know whether or not we have Microsoft teams. So we can because this Library does support the theme of Microsoft teams, so if you're building SharePoint framework Solutions, where you're surfacing them not only in SharePoint but also in Microsoft teams, we can set this up so that we get the the theming to match the team's user interface.

A

Then we need to create an instance of our steam provider and then we call the class spfx themes with the init theme. Handler, we pass in our root Dom element. We pass in our theme, provider and optionally pass in our Microsoft teams, which lets us know if we're in teams or not. uh If there's no theme provider service, if you're using it outside of SharePoint framework, there's also ways to use that without the property all right.

A

And so then we get started using the components so I'm going to essentially go through a demo now, where I'm going to show how to actually use these components. But let me just point out here: on the left hand, side that we have grouped are all our components into different categories. So if you've ever heard me talk about Atomic, Design This is sort of a methodology to break our components into smaller, reusable pieces. So we at the very lowest place, have things called atoms and so showing you something like a button.

A

Let's say that we needed a regular button, so we go into here. The button comes in multiple different flavors, so our documentation shows that we have an enum called who button type and that it has all of these different flavors of it.

A

It shows what the different arguments are for that component and then gives you examples of how to implement each different version of that, and if you click on the show code, it's going to give you the code for how to use that in react, and then you can customize it up so that it looks the way you need it to look all right enough of all that, let's go to our demo page. So I have a SharePoint framework solution running. Hopefully it's still running.

A

uh Let me just double check that everything is good. Let me refresh our page so that we we're sure that everything is going. Okay and I have a button right now that has a dog icon on it. So that's all pretty. Let's start back in uh our project, so here's our SharePoint framework. This is a 1.16.1 project. We have imported the H2O react library and I've also included the H2O icons Library. This is our SAS file with our quiet dependencies equal true, so we've got both of those things.

A

This is our root components: scss module file and, as I pointed out, I have a root class for our component and inside of that I have a global import of the Styles. So this gets us all the styles for all the components that are included in the H2O core Library.

A

So now that we've imported that we're good with that in in our web heart class, we you can see I've got the Imports for the theme provider like I already went over. I have the import for the Sim set. I have an optional import for that. um The fluent UI regular icons in my on init I've consumed the theme provider and then I've initialized.

A

My icons passing in that fluent UI, regular icon set, and that allows me I just want to point out like if you've built a SharePoint framework, 1.16 project, there's a lot of boilerplate code for themesport, that's included, you don't need any of that anymore, so you can clean it out and you just are left with. Essentially your on init and your render method.

A

Okay coming over here quickly.

A

Here's our root component so note that, right here in my class name, I am importing that Styles uh H2O react demo root style, that's the thing that adds the CSS variables so that all the H2O controls can be styled properly and then uh I have my who button right here with that's an icon type with my dog icon and the all that we're doing with the dog icon is giving it the name which is the ID from the fluent UI icon that I want to use, and so you can get this either from Chris, Kent's flycon or from that icon tool.

A

I just showed you, you inspect the element. We do need to improve that uh that interface, so that you can get the IDS on the screen, so you don't have to inspect them, but we'll get to that as shortly. So this is how you then add a button. So now, if I wanted to add something new, let's say I wanted to add something more complicated. So let me come down here. We have organisms. We have cards, here's the H2O document card, so this is a document card layout.

A

That's some people like to use the card layout, and so, if we show this code, we can see that essentially it's a root component for the document card and then it's a bunch of molecules that are the implementation of each one of the pieces of this. So we have the card image. We have the card location, the card title and then this card footer that includes an avatar and the name of the person and the change date, and so I can essentially just copy.

A

All of this put it in my react component here: I need to change. My imports come on, come on format, the document there we go and then I need to get all these Imports and sometimes yeah there we go so what I want to show here is note that the import is coming from the H2O react library, but with a selective import. So there is so this allows you to be very selective about which components get included in your bundle, so that you can make sure that your bundle size is as small as possible.

A

So I'm just going to resolve these various Imports. So there's image. Here's card location there: it is here's card title there that is here's card footer, that's that and now um one of the other things I want to do here is the Avatar image size has an enum whom who Avatar size so I'm gonna, do who oh typo, who Avatar size there it is so I want to include that and then I can do dot 32. So we can oops px32.

A

There's that and I think that's the only one I need all right, let's say, and then, if we come over here and we go to our component, let's see if that renders and everything is coming is. Are we having a build error? Oh it's just being Wicked slow yeah. Let me try restarting it really quickly because I want to let our next speaker have his time come on. Come on.

A

There are cash Oh, no I got an error. What do I got? Oh button type is declared, but oh I should have turned those warnings off sorry, sorry, sorry and where, in demoing areas, Lintz issues are a problem and come on come on come on builds, it should work, but it's not I. Don't know why uh button type is declared, but it's probably never I know I commented it out the way I try starting it again. I, don't know, I, don't know come on and just see. Maybe it's okay there.

A

It is all right, and so then we have our card in our solution. So obviously you can combine all of these uh elements in various different ways to make up your own controls and certainly if you have ideas for controls or you're having problems with one of the controls or um need any assistance. Obviously you can submit issues to our repo, um which we would happily take and try to assist. I also have some documentation in our Solution on contributing.

A

So if you wanted to contribute any controls to our solution, you can check out our contributing documentation. If you have questions or concerns or whatever or want to get more help on getting started, please submit an issue to our GitHub repo and so uh with that I will send it back over. So our next presenter can take over awesome thanks, Julie great demo. These things happen. You got there in the end.