Proceeding our dive into the PnP reusable property pane controls I want to cover the PropertyFieldDateTimePicker control.
The PnP reusable property pane controls is a package that contains a lot of useful controls that can be used in any SharePoint Framework web part’s property pane, if you want to know more about this you can check out the official site here.
To demonstrate the various capabilities of the control I’ve created a sample solution which you can find here. The sample solution contains a simple web part that shows the values of the dates selected with the PropertyFieldDateTimePicker control from the web part’s property pane.
Starting with the resulting UI, here you have an overview of the amazing web part and it’s configuration pane:
In the web part I simply displayed the values that the PropertyFieldDateTimePicker control returns. In the property pane there are various instances of the control and each one has a different configuration.
I won’t cover in detail all the UI instances since the more interesting parts are in the code but here are some interesting configuration.
In the date convention instance the time has been removed from the UI, so if you’re not interested in the time part you can hide it:
Speaking of the time part of the date is possible to specify if you want to display the hour in 12 or 24 format, by default the value is 24 but in the time convention instance I defined the format to be 12 so the result is the following:
Another interesting instance is the hide labels one, by default the control adds the Date and Time labels, however sometimes you need all the space that you can have for your controls and with this configuration you can hide those labels:
One last interesting configuration is the availability to define a custom validation function, in the sample there is a check that the value cannot be empty or has to be a date later than the year 2000, in case the specified value does not meet the requirements an error will be shown:
Show me the code
To use the PnP property controls first you need to install the package:
npm install @pnp/spfx-property-controls --save --save-exact
After the installation of the package you can proceed with the following explanations for the PropertyFieldDateTimePicker control.
To use the control you have to import it in the web part file with the following statement:
import {
PropertyFieldDateTimePicker,
IDateTimeFieldValue,
DateConvention,
TimeConvention,
} from "@pnp/spfx-property-controls/lib/PropertyFieldDateTimePicker";
To use the control is enough to import it, however in the code above I also specified other imports to enable different configurations.
The IDateTimeFieldValue is used to define the type of the properties that will be binded with the control instances, this interface define two different properties:
-
value: the Javascript Date value from the selected date and time. -
displayValue: this property contains the formatted string value of the selected date.
The properties for the web part are defined as following:
export interface IDateAndTimePickerWebPartProps {
basicValue: IDateTimeFieldValue;
customFormatValue: IDateTimeFieldValue;
dateConventionValue: IDateTimeFieldValue;
timeConventionValue: IDateTimeFieldValue;
hideLabelsValue: IDateTimeFieldValue;
validationValue: IDateTimeFieldValue;
deferredValidationValue: IDateTimeFieldValue;
}
The control instances are defined in the getPropertyPaneConfiguration method, to separate them I placed a PropertyPaneHorizontalRule just to have a nicer UI.
Basic instance
Starting with the basic instance, here is the code:
PropertyFieldDateTimePicker("basicValue", {
label: strings.BasicConfigurationLabel,
initialDate: this.properties.basicValue,
onPropertyChange: this.onPropertyPaneFieldChanged,
properties: this.properties,
key: "basicDateTimeField",
})
This instance contains all the minimum required fields for the control to work, those required fields are:
-
label: a text to be specified as a label of the control. -
initialDate: the initial Date value to be set. -
onPropertyChange: the method that will handle the change. -
properties: the properties of the parent web part. -
key: an identifier of the control instance.
Custom format
Aside of the required properties there are also many other capabilities, one of those is the ability to specify a custom formatting for the date value. The control has a property named formatDate which accept a method that returns a string with the formatted Date value.
PropertyFieldDateTimePicker("customFormatValue", {
label: strings.CustomFormatLabel,
initialDate: this.properties.customFormatValue,
onPropertyChange: this.onPropertyPaneFieldChanged,
properties: this.properties,
key: "customFormatDateTimeField",
formatDate: (date: Date) => {
// return the date formatted as dd/MM/yyyy HH:mm
return `${date.getDate()}/${date.getMonth() + 1}/${date.getFullYear()} ${date.getHours()}:${date.getMinutes()}`;
},
})
The formatted value will then be set to the binded property using the displayValue property of the IDateTimeFieldValue interface.
Date convention
With the dateConvention property is possible to define what value is possible to select in the control, the property accepts a value from the DateConvention enumerable type:
-
DateTime: allows the selection of the date and time. -
Date: allows only the selection of the date.
The following is the control instance configuration:
PropertyFieldDateTimePicker("dateConventionValue", {
label: strings.DateConventionLabel,
initialDate: this.properties.dateConventionValue,
onPropertyChange: this.onPropertyPaneFieldChanged,
properties: this.properties,
key: "dateConventionField",
dateConvention: DateConvention.Date,
})
Time convention
The control exposes also a timeConvention property, this property accepts a value from the enumerator TimeConvention, the available values are:
-
Hours12: will display the time divided in AM and PM. -
Hours24: will display the time with a value from 0 to 23.
The control instance is defined as follow:
PropertyFieldDateTimePicker("timeConventionValue", {
label: strings.TimeConventionLabel,
initialDate: this.properties.timeConventionValue,
onPropertyChange: this.onPropertyPaneFieldChanged,
properties: this.properties,
key: "timeConventionField",
timeConvention: TimeConvention.Hours12,
})
Hide labels
With the boolean property showLabels it’s possible to define if the Date and Time labels are shown or not, by default it’s value is true:
PropertyFieldDateTimePicker("hideLabelsValue", {
label: strings.HideLabelsLabel,
initialDate: this.properties.hideLabelsValue,
onPropertyChange: this.onPropertyPaneFieldChanged,
properties: this.properties,
key: "timeConventionField",
showLabels: false,
})
Validation
The control offers the ability to define, using the onGetErrorMessage property, a method that can validate the selected date and time and returns a string if the validation failed:
PropertyFieldDateTimePicker("validationValue", {
label: strings.ValidationLabel,
initialDate: this.properties.validationValue,
onPropertyChange: this.onPropertyPaneFieldChanged,
properties: this.properties,
key: "validationValueField",
onGetErrorMessage: this.validateDateTime
}),
In the sample the validateDateTime function is the following:
protected validateDateTime = (dateValue: string): string => {
if (!dateValue) {
return strings.Validation.DateIsRequired;
}
const date = new Date(dateValue);
if (date.getFullYear() <= 2000) {
return strings.Validation.DateGreaterThan2000;
}
return "";
};
The function simply returns a string message if the data is undefined or if the year of the selected date is less or equal than the year 2000.
Deferred validation
Other than the ability to specify a custom validation method there is also the ability to specify after how many milliseconds the validation will be performed. The default value is 200 milliseconds.
This control instance is defined as follows:
PropertyFieldDateTimePicker("deferredValidationValue", {
label: strings.DeferredValidationValueLabel,
initialDate: this.properties.deferredValidationValue,
onPropertyChange: this.onPropertyPaneFieldChanged,
properties: this.properties,
key: "deferredValidationField",
deferredValidationTime: 2000,
onGetErrorMessage: this.validateDateTime
}),
Conclusions
The PropertyFieldDateTimePicker is a convenient control to enhance your web part configuration, it allows you to quickly handle a date and time value without worrying about creating anything. If you want to have a look at the official documentation you can find it here.
Hope this helps!
Top comments (0)