Calendar

The Calendar shows Dataverse appointments the way Outlook does — and tasks, and any other table the server registers — by day, work week, week or month, or as a week's list. Its toolbar moves between ranges and layouts, a busy day collapses into + more, and appointments at the same time sit side by side. It reads the rows of the range on screen as you move to it, through the same query and security as a grid, and shows their days and times in the user's time zone, as every date on the portal is shown. It comes as an add-on package on each stack, drawn in your Fluent UI theme.

What it shows

Without Regarding, the calendar shows every row the user can read of the tables it shows. It reads the tables the server registers for calendars — notes and every activity table, and any other registered with ForCalendars — each dated by its own column: an appointment by its start and end, a task, phone call, letter or fax by its due date. Appointments and tasks show at first; the others the user may read are offered in the toolbar's Show menu, switched off. DefaultTables (React: defaultTables) chooses the ones shown at first, and Tables (React: tables) the ones it may show at all. The calendar adds its range, and the regarding record, as conditions of its own, so a view can narrow what it shows but never widen it.

Access

The calendar lists only the appointments the user may read, and lets them move one only where they may change it. A portal usually gives contacts the appointments they are invited to: RowsInvolvingContact on requiredattendees and optionalattendees reads them through the appointment's party lists, without making them the contact's own.

Like other activities, an appointment reaches the portal only when its description starts with *WEB*, unless its table is in SecurityOptions.PortalVisibility.UnfilteredActivities. A calendar portal adds appointment there, as above, so staff book appointments in Dynamics and Outlook as they always do.

The portal's application user needs read on appointments in Dataverse as well. Dataverse grants every activity type through one set of privileges, so appointments are covered by the read on activities the Power Portals Pro Application User role already holds.

Recurring appointments

An occurrence of a recurring appointment is shown like any other appointment, with the repeat icon beside its subject. Clicking one asks whether to open that occurrence or the whole series; moving or resizing one changes that occurrence alone. The calendar shows the occurrences Dataverse has written: Dataverse writes those of a series ahead of time, as far as the environment's expansion window — twelve months by default — and the later ones as time passes, so a series that never ends shows a year of occurrences at a time.

Free, busy and out of office

An appointment is drawn by how it shows its time, as Outlook draws it: busy as a tint with a bar beside it, free with the bar alone, tentative striped and out of office in purple, read from its status reason. A completed appointment shows as busy, a canceled one as free with its subject struck through. In a month, where an appointment with a time is a dot beside it, and in the agenda's rows, only the color shows. Appointments you provide take ShowAs and Canceled (React: showAs and canceled), and each is drawn with a class — ppp-calendar-appointment-free, -busy, -tentative, -out-of-office and -canceled — to restyle it by.

Creating and editing appointments

In an Editable calendar that loads its own appointments, selecting a time opens a new appointment over it, about the Regarding record, and clicking an appointment opens its details as a form, saved with the same table, row and column security as any record. Moving or resizing a row saves it — its start, its end and whether it takes whole days — where the user may change the row and those columns and it isn't completed, canceled or inactive; a row whose table keeps one date, such as a task's due date, moves but doesn't resize, and one dated by when it was created stays put. Clicking a row of another table opens its form: the columns its registration shows, or your own form for the table, a MultiTableForm inside the calendar (React: forms). An appointment's details and another table's form open in a dialog in the center, or, with FormLocation (React: formLocation), in a side panel on the left or the right. Its attendees are edited with PartyListEdit, which ColumnEdit also uses for every party list — an email's To, From and Cc among them. As the user types, it suggests the contacts, accounts and users they may read and link to (Read and Append To) that have an email address, a table without both never searched; picking one adds it as a chip. Where the environment allows messages to unresolved email recipients — or AllowUnresolvedEmailAddresses says so — an email address that matches no record is added on its own with Enter. An appointment's Regarding offers the tables it can point to whose records the user may read and link to; RegardingTables (React: regardingTables) narrows them to the ones you name. Handle OnRangeSelect to create appointments your own way instead, and SaveChange (React: onAppointmentChange) to save moves your own way.

Making an appointment repeat

In an Editable calendar, an appointment's form offers Repeat: daily or on weekdays, on days of the week, monthly or yearly — on the date or on the weekday, such as the second Tuesday — every so many, and ending never, after a number of times or on a date. Dataverse lays the occurrences out in the user's time zone, so a meeting at ten stays at ten across a change of clocks. A series opens as a form of its own, where how it repeats can be changed, and an occurrence's Delete offers deleting it or the whole series. Repeat is offered to users who may create recurringappointmentmaster records — and, for an appointment that already exists, change and delete it, since it becomes the series. Grant the series as you grant appointments, and give the portal's application user Read on Connection in Dataverse: making an appointment a series reads its connections, and Dataverse refuses the save without it.

A new appointment, or a change to one, becomes a series in the same transaction as the rest of its save: the save sends an AddRecurrenceRequest beside the appointment's own, so the appointment is never saved without its series, nor the series without it. Dataverse creates the series from the appointment, with its attendees, and removes the appointment. A page building its own form can send the request the same way.

A series that has begun changes from its next occurrence on, as in Outlook: Dataverse keeps the occurrences that have ended as a series of their own, sharing the series' groupid, so they stay as they took place. The count a series ends after is of the whole series — the portal reads and saves it with the occurrences already kept — and a series with none left to come can no longer be changed. Switching All day fits the times to it: on, the whole days they fall on; off, nine o'clock on the first of them for half an hour. Dataverse keeps an all-day appointment as a day; the portal shows and saves it on the user's own day, whatever their time zone.

Appointments you provide

Pass Appointments instead, and the calendar shows those rather than reading Dataverse. With Editable on, appointments can be moved, resized and created by selecting a range: SaveChange (React: onAppointmentChange) saves a move, and returning false puts the appointment back; OnRangeSelect receives a selected range, and OnAppointmentClick an opened appointment.

An appointment's details

Resting the pointer on an appointment shows its subject, when and where it is, and clicking one opens a dialog of its details, read from Dataverse as a record page reads a record — through the same table access and column security — and shown read-only. Handle OnAppointmentClick (React: onAppointmentClick) to do something else on a click, such as opening a page of your own. The calendar's rows, its tooltips and the details dialog can each be drawn your own way: see Custom Rendering.

Toolbar buttons

Put your own controls in the toolbar with ToolbarItems (React: the calendar's children), ahead of the search box, as a grid's toolbar buttons are. A CalendarButton is handed the calendar when clicked: the period it shows, the record it is about, and CreateAppointmentAsync and RefreshAsync (React: createAppointment and refresh). NewAppointmentCalendarButton starts a new appointment as selecting a time does — from the next half hour when the period shown takes in today, and otherwise from 8:00 on its first day — and is shown only where that starts something: an Editable calendar whose host handles OnRangeSelect, or that loads its own appointments for a user who may create them.

Layouts

The calendar lays its appointments out by the hours of a day, a work week or a week, as a month of days, or as an agenda list, and its toolbar has a picker to switch between them. DefaultLayout (React: defaultLayout) is the one it opens in, a week unless you choose another. Layouts (React: layouts) keeps it to the ones you name, listed in your order: name one, and the picker goes and the calendar stays in it. Each layout has a page of its own: Day, Work Week, Week, Month and Agenda.

Views, filters and search

Offer views in ViewIds — Dataverse views, each of its own table — MultiTableViewIds, views of several tables registered with AddMultiTableView or kept in Dataverse, and CustomViewDefinitions, views defined in code, and the toolbar has a picker to choose what the calendar shows. DefaultViewId is the one it opens on. The search box finds each table's search columns as a grid's search does. Turn it off with AllowSearch.

With AllowFiltering, the toolbar's Filter menu offers Edit filters, which opens the filters of the tables shown, a tab for each in order of its name, each the dialog a grid's Filter button opens: conditions on the table's columns, nested in groups, and related tables to filter by, over the columns and tables the user may read. A tab's columns are read when it is first opened. The filters take the place of the view's own until the user picks another view. It is off by default, because the user can take away every filter the view has.

With AllowSavedViews (React: allowSavedViews), a signed-in user can save what the calendar shows — the view, their filter, the tables shown and the layout — as a view of their own, choose their default view and hide the ones they don't use, from the toolbar's Filter menu. A view of appointments alone is offered on the grids of appointments too, and a view of several tables on timelines. How views are saved, changed and shared is on the Saved Views page.

Keeping its place in the URL

Name a query parameter in PersistedStateQueryParameter, and the calendar keeps its layout, the period it shows and the appointment view picked there, so a reload or a shared link opens it where it was left. What it would open on anyway is left out — the date while the period shown includes today, so a link to the current week keeps following today. The search is kept too when you turn on IncludeSearchInPersistedState; it is left out by default, since what users search for can be sensitive. Each change replaces the browser's history entry, so Back leaves the page rather than stepping back through every week. Both stacks write the same value, so a link made on one opens the same calendar on the other.

Packages

The calendar is an add-on: PowerPortalsPro.Web.Blazor.Calendar on Blazor and @powerportalspro/react-calendar on React. Add the package beside the framework's own to use it.