Skip to content

Commit

Permalink
readme updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@rwilson504
rwilson504 committed Dec 17, 2024
1 parent fbfe987 commit 968f01e
Showing 1 changed file with 61 additions and 16 deletions.
77 changes: 61 additions & 16 deletions Calendar/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,13 @@ This control has been designed to work in both Canvas and Model apps. Because o
![Control Overview](./images/calendarcontrol.gif)

Canvas

- To ensure data loads correctly in Canvas we must use collections instead of CDS datasource directly.
- There are output parameters that are defined in the app which will pass back data when an item is clicked on, an empty time span is selected, or the calendar range has been updated. These output parameters will allow you to create your own functionality in the Canvas app for updated or creating records.
- To set the default language for the calendar you can utilize the Language() function to pass the users current browser language into the calendarLanguage property.

Model

- Clicking on and event will open the record for editing.
- Clicking on an empty timespan will open a new record form, and will pass in the start, end, and resource field data.
- Calendar will default to the users currently selected language in their users settings if that language is available otherwise it will utilize English.
Expand All @@ -21,11 +23,13 @@ Model
Make sure you have enabled PCF components for Canvas apps in your environment. For instructions on that [Click Here](https://docs.microsoft.com/en-us/powerapps/developer/component-framework/component-framework-for-canvas-apps)

# Sample Application

If you would like to try this component download the sample solution below which includes a Model and Canvas app you can utilize.

[Download Sample App](https://github.com/rwilson504/PCFControls/raw/master/Calendar/Sample/CanvasCalendar_1_0_0_4_managed.zip)

# Model Configuration

To add the calendar in a model view you can do the following.

Create a new view or select an existing one. You need to make sure that any columns you utilize in the control properties are in the view.
Expand All @@ -51,23 +55,55 @@ Select the Calendar Control
![Select Calendar Control](./images/ModelCalendarShowAs.png)

Set the properties of the control.
- **Event Name Field** This will be the title for the events. Enter the logical name of the attribute in this fields. Ex. raw_name
- **Event Start Field** This will be the start time for the events. Enter the logical name of the attribute in this fields. Ex. raw_start
- **Event End Field** This will be the end time for the events. Enter the logical name of the attribute in this fields. Ex. raw_end
- **Event Color Field** This will change the color of the event. You can use a color field on the event or you can utilize a color field from the resources. Enter the logical name of the attribute. Ex. on Event raw_color, Ex. on Resource raw_resource.raw_color.
- **Default Event Background Color** Specify the default background color for events if not using a field to define the color. Value should be in Hex color format, eg. #3174ad
- **Event Id Field** (Do Not Use In Model, for Canvas Only were data is supplied by a collection)
- **Resource Field** If you want to utilize resources enter the logical name of the lookup field for the Resource.
- **Resource Name** To use a name field for the resource that is not the default name field you can enter it here. Ex. raw_resource.raw_specialname. Otherwise you can leave this blank and it will use data from the default name field.
- **Week Start Day** Select the day the week should start on. If left blank or 0 this will be based upon your locale. (1=Sunday, 2=Monday, 3=Tuesday, 4=Wednesday, 5=Thursday, 6=Friday, 7=Saturday)
- **Work Week Days** Select the days you would like to show on the work week. For example enter 2,4,6 to only show Monday, Wednesday, and Friday. If left blank it will display Monday-Friday. (1=Sunday, 2=Monday, 3=Tuesday, 4=Wednesday, 5=Thursday, 6=Friday, 7=Saturday)
- **Get All Resources** Determines if all resources will be returned even those that don't have any events on the calendar. Possible values are true or false.
- **Today Background Color** Sets the background color for the time slots that cover todays date.
- **Default Calendar View** Set the default calendar view. Possible values are "month", "week", "work_week", "day", "agenda"
- **Calendar Date** (Do Not Use In Model, for Canvas Only)
- **Calendar Language** Allows you to set the default language/culture for the calendar. If you leave this blank it will default to the users current language in Dynamics if it's available or you can specify a language if you always want the calendar to show up in that language.

## **Input Properties**

| **Property** | **Description** | **Example/Default** |
|-------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------|
| **Event Name Field** | This will be the title for the events. Enter the logical name of the attribute in this field. | `raw_name` |
| **Event Start Field** | This will be the start time for the events. Enter the logical name of the attribute in this field. | `raw_start` |
| **Event End Field** | This will be the end time for the events. Enter the logical name of the attribute in this field. | `raw_end` |
| **Event Color Field** | This will change the color of the event. You can use a color field on the event or utilize a color field from the resources. Enter the logical name of the attribute. | `raw_color`, `raw_resource.raw_color` |
| **Default Event Background Color** | Specify the default background color for events if not using a field to define the color. Value should be in Hex color format. | `#3174ad` |
| **Event Id Field** | *(Canvas Apps Only)* For Canvas apps where data is supplied by a collection. | |
| **Resource Field** | If you want to utilize resources, enter the logical name of the lookup field for the Resource. | |
| **Resource Name** | To use a name field for the resource that is not the default name field, enter it here. Leave blank to use the default name field. | `raw_resource.raw_specialname` |
| **Get All Resources** | Determines if all resources will be returned, even those that don't have any events on the calendar. | `true` or `false` |
| **Week Start Day** | Select the day the week should start on. If left blank or `0`, this will be based on your locale. (1=Sunday, 2=Monday, etc.) | `0` (default) |
| **Work Week Days** | Select the days to show on the work week. Enter days as comma-separated values. If left blank, it will display Monday-Friday. | `2,3,4,5,6` |
| **Today Background Color** | Sets the background color for the time slots that cover today's date. Value should be in Hex color format. | `#eaf6ff` |
| **Weekend Background Color** | Sets the background color for the time slots that fall on weekends. Value should be in Hex color format, including transparent Hex options. | `#ff000033` |
| **Default Calendar View** | Set the default calendar view. Options are `month`, `week`, `work_week`, `day`, or `agenda`. | `month` |
| **Available Views** | Select which calendar view buttons show up for the user. Provide a comma-separated list of view names: `month, week, work_week, day, agenda`. | `month,week,work_week,day,agenda` |
| **Calendar Date** | *(Canvas Apps Only)* Allows you to set the initial date displayed on the calendar using a date value from a Canvas app. | |
| **Calendar Language** | Set the default language/culture for the calendar. Defaults to the user's current language if left blank. Example: `en`, `fr`, `de`. | `en` (default) |
| **Calendar Scroll To Time** | Set the default hour for the day/week view to automatically scroll to. Enter the hour as a number (0 - 23). | `8` |
| **Calendar Min Hour** | Set the earliest hour displayed on the calendar. Enter the hour as a number (0 - 23). | `0` |
| **Calendar Max Hour** | Set the latest hour displayed on the calendar. Enter the hour as a number (0 - 23). | `23` |
| **Calendar Step** | Set the interval (in minutes) between time slots on the calendar. | `30` |
| **Time Slots Per Hour** | Divide an hour into smaller time slots. Options: `1, 2, 4, 6`. Default is `2`. Example: `4` divides an hour into 15-minute slots. | `2` |
| **Day Layout Algorithm** | Controls how events are displayed to avoid overlaps. Options: `overlap` or `no-overlap`. | `overlap` |
| **Selectable Calendar** | Allows you to enable or disable calendar slot selection. Use `true` to allow selection or `false` to disable. | `true` |
| **Event Selectable** | Allows you to enable or disable event selection. Use `true` to allow selection or `false` to disable. | `true` |
| **Event Popup** | Determines whether truncated events (e.g., "+X more") display in a popup. Use `true` to enable or `false` to disable the popup. | `false` |

## **Output Properties**

| **Property** | **Description** |
|-----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Selected Record Id** | *(Output)* Returns the ID of the selected event. |
| **Selected Slot Start** | *(Output)* Returns the start date/time of a selected slot. |
| **Selected Slot End** | *(Output)* Returns the end date/time of a selected slot. |
| **Selected Slot Resource** | *(Output)* Returns the resource ID for a selected slot, if available. |
| **Calendar Range Start** | *(Output)* Returns the start date of the current calendar range. |
| **Calendar Range End** | *(Output)* Returns the end date of the current calendar range. |
| **Current Calendar Date** | *(Output)* Provides the current date the calendar is set to. |
| **Current Calendar View** | *(Output)* Provides the current view the calendar is set to. |
| **Empty Time Slot Was Selected** | *(Output)* Notifies when an empty time slot is selected. |
| **Record Was Selected** | *(Output)* Notifies when an event is selected. |

## Using In Sub-Grid

If using this control in a Sub-Grid you will need to add it to the form using the Classic Editor.

![Classic Editor For Sub-Grid](./images/ModelCalendarSubGrid.png)
Expand All @@ -76,6 +112,7 @@ To set the height for the calendar update the number of rows the subgrid should
![Sub-Grid Rows for Calendar](./images/ModelCalendarSubGridHeight.png)

# Canvas Configuration

Using the control in Canvas requires more configuration due to the limitations and differences inherit between Model and Canvas apps. In a canvas app the actions such as creating a new record or updating an existing one need to be implemented by the person creating the app. The control will provide you with output which will allow you to access data from the calendar and complete those interactions.

*Important Notes:*
Expand All @@ -86,6 +123,7 @@ Using the control in Canvas requires more configuration due to the limitations a
- Because PCF Code components are not currently in Preview from Microsoft there are some paging bugs that limit the number of records return when using a CDS entity directly, instead you will need to utilize a Collection to get the data. directions on how to do this are below.

## Events Only

To just get the events and display them on the calendar we must utilize a simple collection to get all the events. Because Canvas have some paging issues right now we will need to load the CDS data into a collection, otherwise the number of records will be constrained to 25.

The following code can be added to the OnVisible event of the Canvas form or to a Toggle switch that can update the data when it's been checked.. The collection name will be calendarEvents and the CDS entity we are pulling from is called Events. Additionally you can add filters when creating the Events entity if you would like to only show certain events.
Expand All @@ -104,9 +142,11 @@ Here are the input properties for the control. If the eventId property is not f
![Input Properties](./images/CanvasCalendarEventsOnlyAdvancedProps.png)

## Events and Resources

To get Events and Resource data we will need to utilize more complex Collections to pull all of our data together. This is due to how Canvas app pull back data for lookups.

### Return Only Resources That Have Events

The configuration below will load the Events and include information about their resources. Also because we will be utilizing a control you will need to add in the EventId and set that parameter on the control.

Here you can see that there are 5 resources in our Resource data.
Expand Down Expand Up @@ -151,7 +191,8 @@ Here are the input properties for the control


### Return All Resources and Events
To return all resources including those who don't have any events for the current time period you will need to perform some additional work on the Collection.

To return all resources including those who don't have any events for the current time period you will need to perform some additional work on the Collection.

![All Resources in Model App](./images/CanvasCalendarAllResourcesResourceHeader.png)

Expand Down Expand Up @@ -210,6 +251,7 @@ Here are the input properties for the control
![Input Properties](./images/CanvasCalendarAllResourcesAdvancedProps.png)

## OnChange Event

The data returned from the control will be attached to the Canvas Control element. There are currently 3 defined types of output changes that occur.

* RecordSelection, occurs whenever a user clicks on a calendar event.
Expand All @@ -234,9 +276,11 @@ This is an example of the OnChange event on the Calendar Control which will allo
![Calendar OnChange Event](https://user-images.githubusercontent.com/7444929/140170012-5b34c219-0afa-42b0-963a-1d8d3dc3e708.png)

## Setting the Calendar Date

If you would like to set the Calendar date to something other than Today you can do so in two ways. If you leave the calendarDate property on the control empty it will default to Today.

### Default On App Load

The first way is if you just want to default the calendar once upon app load. In this case you can set a variable during the OnStart of your app.

![Calendar Start Date Variable](./images/CanvasCalendarDateOnStart.png)
Expand All @@ -250,6 +294,7 @@ Finally you will need to make sure the OnChange handler of the control updates t
![Calendar On Change](./images/CanvasCalendarDateOnChange.png)

### Allow User to Select Date

To allow the user control of the calendar date you can utilize a Date control.

First start by creating a variable on the OnStart of your application and setting the default date you would like to have.
Expand Down

0 comments on commit 968f01e

Please sign in to comment.