Microsoft 365 Community Community Demos, 3 Jul 2023

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: SPFx framework at Microsoft - Accelerator Domain Models

Description

In this 18-minute developer-focused demo, Daniel Turley facilitates an understanding of the “SPFx Solution Accelerator” framework by going deep into the Rhythm of the Business Calendar sample app to see patterns and practices for building enterprise-class apps on SharePoint. This accelerator, inspired by Domain Driven Design, has evolved since SPFx v1.0. Today’s focus is on “Entities” (including class, relationships, validation, categories and states) and the implementation of a rich entity domain model for your application.

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

Demo Presenter
• Daniel Turley (Avanade)

Supporting materials
• Sample - Rhythm of Business Calendar | https://github.com/pnp/sp-dev-fx-webparts/tree/main/samples/react-rhythm-of-business-calendar
• Sample - SPFx Solution Accelerator Deep Dive | https://github.com/pnp/sp-dev-fx-webparts/tree/main/samples/react-rhythm-of-business-calendar/documentation
• AppSource - Rhythm of Business Calendar | https://appsource.microsoft.com/product/office/WA200004833
• Documentation – Entities | https://github.com/pnp/sp-dev-fx-webparts/blob/main/samples/react-rhythm-of-business-calendar/documentation/entities.md

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

A

Foreign, my name is Dan Turley and I'm. A full stack developer at avanade I've been working with SharePoint for over 10 years, starting with SharePoint 2010, most recently as part of the productivity Studio utilizing SharePoint framework to build business apps so today, I'll be presenting on entity domain models in our spfx solution, accelerator, but first a quick overview of the accelerator.

A

It's a set of patterns, reusable code components and tools that I created for building business apps on the SharePoint platform, it's evolved over the last six years and we've used it in the productivity Studio to build a dozen business apps over that time and the accelerator is open source we've published a complete sample app to demonstrate its features. The sample app is named, react rhythm of business calendar, so some high level features of the accelerator. We have guidelines for the solution structure to organize your domain models, Services components and schema.

A

We have a robust entity domain model with features like change, tracking validation and relationships, and this is what I'll be going into detail on today. There's also a services framework with provided services for SharePoint list data, time zones, users and groups and more.

A

We also have Dynamic provisioning of SharePoint lists for app setup and upgrade experiences. There are react, components for View and edit panels and dialogues. Asynchronous data live update, controls, a wizard and more. We have tooling to support development teams and environments, and, last but not least, a feature called live update which ensures users are always collaborating with the latest data entities. Are the implementation of a rich domain model for your application and it's inspired by the domain-driven design approach to software development.

A

We have a base entity class that you can use for any data source and a list item entity class which adds standard fields that every SharePoint list has such as title author, editor that created and modified dates.

A

Yeah every entity supports change tracking and we implement this by keeping all of the entities. Internal data in a separate State object and you expose the state by writing simple getter and Setter properties on the entity class and with this state object we can then create a copy of the state. Before the user begins editing fields on the screen, then we can compare the before and after state to detect. If the user has made any changes, you can store many different types of data in the state, including all the JavaScript Primitives arrays sets Maps.

A

Custom objects, also support validation and you declare rules on The Entity. We have built-in rules for a minimum and maximum values maximum length for Strings and arrays. Whether a value is required and also a couple of rules for URLs and email addresses, and of course you can write your own validation rules too.

A

You also have delete and soft delete support basic text search. This is a feature for enabling a filtering of a list of entities on the client side. So imagine a UI that displays a list or a collection of items and there's a filter box at the top of the screen.

A

When you define your entity class, you can specify which data from The Entity is searchable and there's built-in functions for filtering entities based on text input.

A

We also have a pattern for defining sorting and filtering functions, and there are helpers that allow you to easily combine multiple sorts and filters and, lastly, relationships relationships between entities are a first class construct in the accelerator. You define them as navigation properties on two related entities, and the accelerator supports one to many and many to many relationships and in code you can program against either side of the relationship, and both sides will be kept in sync and relationships can also participate in change tracking.

A

So, for instance, you could design and edit experience around a parent-child relationship and you can detect any changes to the related entities and then accept or revert all of those changes. All right. Let's uh make this discussion a little more concrete. I have here a simple illustration relating some of the entities in the rhythm of business calendar solution to the SharePoint lists we use for the back end.

A

So the business requirement here is to have events that are tied to values and we group those values into refiners, and all of this is configurable by the end user.

A

So on the left here, where it says refiner an example could be department and where we say refiner value examples could be sales, marketing or engineering, those will be departments.

A

So in this solution we have an events list see on the left side for SharePoint list. We have an events list that has a multi-valued lookup column, to the values list and from the values list, there's a lookup column to the refiners list, and so in the entities we can represent. Those relationships.

A

I just want to quickly show you how to find the documentation for all of this. So if you go to the sample page for the rhythm of business, calendar and scroll, all the way down, there's a section here and there's a link directly to the documentation on entities which is what we're talking about today.

A

Right so moving on I want to quickly revisit the user interface for the Calendar app and provide some context around where entities fit into the picture before we dive into some code. So here's the Calendar app, you can see all of the events for the month of May and on the left. We have our refiners.

A

So we have refiners for team type and Country and then the values underneath of that refiner. Now, if I click on one of these events, I have this little pop-up, you can see this event here. Candidate profile reviews is associated with this blue Human Resources, refiner value, and also this review refiner value which comes from the type refiner.

A

Now, if I uncheck this, you know you can see it filters the view all of these Human Resources events disappear so in the code we're using entity relationships between all of these entities to make this logic more robust and easier to maintain. Now, if I open this event, what I want to do is demo the edit experience.

A

If I go and edit, if I change the title.

A

Now so this text box is being uh the value is rendered directly from the property on the entity. So we have an event entity that is driving the data here and as I type in the Box. The changes are immediately written back to that property on The Entity, but I should mention that when I open this edit panel, it automatically took a copy of the state for the event entity, and so before I started making changes.

A

We have a copy of what the title was before then now what I could do is, let's say, I accidentally clicked the close button, because we have those the copy of the state. We can compare them and know that I've made changes and we can drive UI experiences like this little pop-up asking me. If I want to keep my changes or discard them and if I choose to discard them, then we can simply erase the current state of the entity and go back to that snapshot copy that we made before the user started.

A

Editing all right. Let's see some code, okay, we're going to look at how to define a basic entity class, for example. We're going to create a category entity that has a couple of properties, one for the numerical order, so this could indicate how the user wants to sort this category in the UI and a property for the users who will own this category.

A

So the first thing we do is define a class and derive it from one of the entity-based classes, and then we use this I State interface to define the data for The Entity, and the data is anything that we want to participate in the change tracking or something that will be loaded or saved from the backend data store that we can't calculate from existing data.

A

The next thing, you'll notice, is the Constructor.

A

Now this one's rather long, um and that's because it's a list item entity. So we have a lot of SharePoint related data, but if you'll notice, all these parameters are optional. So when creating a new instance in your code, you don't need to pass anything to the Constructor and these values will be set later by Services when you save it to backend SharePoint list.

A

Also in the Constructor we set default values for each of the fields. In the state, so usually, this is just zeros for numbers and empty strings, an empty array, and finally, we have Getters and Setters to expose the data now notice. We use the state property that is defined in the base class.

A

These property accessors can be simple, as you see here, or they can can contain business Logic, for example, if you had properties for the start date and the end date, you could write logic in each of the Setters to ensure that the end date always comes after the start date, all right. Let's move on and add some validation to this entity, so we're still on the category entity and what you'll see is we've added a couple of static fields to the class definition.

A

We split out the validations per field, and we do this so that we can easily reference these from the UI, so we can put validation around uh like a specific input field. So the first rule here we have is for the order property and it says that it has to have a minimum value of zero right. It can't be negative.

A

The second validation rule we have is for the owner's field, and we have two rules saying that the field is required and then it can have at most five users, and so you can see we can use our built-in required validation rule even on an array, and that will make sure that the array isn't null or undefined or empty all right now towards the bottom of the class definition.

A

There's this protected method, validation, rules which we're overriding from the base class and we simply concatenate the rules for each of the individual fields into one large array of rules, and so this is what's used to determine the overall overall, that the entity is valid, and so we'll see more about that in just a second okay. So now we're going to look through some example code on how to use an entity for this example we're going to assume that we've retrieved a category from somewhere and the user is about to make some edits.

A

So here in step, one before making any edits. What we need to do in code is call a snapshot function and this will take a copy of the entity's internal state. Now we're going to pretend that the user is making edits, they set the order to two and they empty out the users array.

A

Then, let's pretend in step three, that the user is trying to click the save button. So the first thing we would do in our code is check if the entity is valid and we can do that by simply calling the valid function, and this will run all of the rules that we've defined against this instance of The Entity, and in this case, because the user is set, the owner's array to empty and that's a required field, the validation should return false.

A

Now, let's imagine that the user sees the validation error and fixes it they've added some users.

A

Now, when they click the save button again, we can run our validation logic and it should return true and then the next thing we would do is use our services to save that entity back to, let's say a SharePoint list, for instance, and if that completes successfully, then what we need to do is call the immortalize function which what this does is simply delete: the snapshot, the copy of the internal state that we took earlier.

A

Okay. So, alternatively, if the user doesn't choose to save their changes, if they want to cancel all of their edits, we can use the revert function and what this does is set the current state to that snapshot that we took so we're reverting any changes that they made all right. Moving along.

A

uh Let's explore entity relationships for a bit. What I have here is a basic meeting entity, so this is going to be a one-to-many relationship with the category entity that we are just working with and a meeting will have one category and a category it can be associated with zero or more meetings.

A

So the first thing we'll need to do is, in the istate interface, um add a field for the category that's associated with this meeting, and if you think about the the back end SharePoint list, this would correspond with having a lookup field on the meetings list that points to the categories list now down here in the body of the entity class. We want to define a read-only field that will be the navigation property for this relationship and we use the this generic interface for the type I.

A

Many to one relationship of category, which you can think of saying there will be many meetings to one category now here in the Constructor. We are initializing the field and we have to specify the name of the corresponding field on the category entity. So, on the category entity, we will have a navigation property called meetings which we'll see in a second, which represents the other side of this relationship, and this last parameter is the name of the field in the state.

A

Now we have to specify these parameters because it is possible to have business logic where there's more than one relationship between the same two entities, and so what this allows us to do is specify which fields are being used in this relationship. Okay, just a minute left. So now what we're going to do is Define the other side of the relationship, we're going to go to the category entity, and you recognize it from before the things that we've added are the navigation property for meetings and we've initialized it.

A

Similarly in the Constructor, and so the last thing that I want to do is quickly show you how easy it is to use these relationships after we have them set up.

A

So the first thing I want to do here is create a new category entity and we'll set the title to Green.

A

Then we're going to create a new meeting entity meeting one and I can use the category navigation property to set the category for this for meeting one and for meeting two I'm going to create and I can use the other side of the relationship. I can go from the category and add the meeting to it and then you'll see if we were to run these statements. uh Getting the category for meeting two I can get the title it would.

A

Output Green from the category I can ask how many meetings are associated with it at this point, that would be two. The next thing I could do maybe is from the category. I could remove meeting two from the relationship and you can see now. The output would change so meeting two. If I try to get the category, it would return null and if I ask the category how many meetings are associated with it, it should only return one all right.

A

That is all we have time for today, so in the next demo I plan to cover the technical implementation for the live update feature. uh Thank you. So much back to you, Hugo foreign.