Discovering the PnP Property Code Editor control in SPFx

Proceeding our dive into the PnP reusable property pane controls I want to cover the PropertyFieldCodeEditor 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 how the PropertyFieldCodeEditor control works from the web part’s property pane.

Starting from the resulting UI, the web part shows only one of the property field values because I wanted to focus more on the property pane:

Instead, the property pane, has a lot to show:

Every instance of the control displays a text box and a button. The text box shows (partially) the inserted code. If the user clicks on the text box or on the button a panel will be displayed to enable the code editing:

In the panel there are three buttons that enable different actions:

• Save: allows the user to save the changes made to the inserted code and dismiss the panel.
• Cancel: allows the user to cancel any editing made to the code and dismiss the panel.
• Format code: allows the user to format the code accordingly to the language specified in the control property. If no language is selected it will simply do nothing.

If I insert some sample code in the panel it will look like the following screenshot:

Once clicked on the Save button my web part will display the inserted code:

In case the language property is defined you will have some visual cues to better read the code, for example, if I specify JSON as language the resulting will be:

I also want to show how the format button works. Let’s say we have the following situation:

I know that it’s not a complicated JSON but in my opinion it’s pretty ugly to look at it with no formatting. Clicking on the Format code button the code will be formatted and more readable:

The code editor has many out of the box useful features. A couple of examples are, in the code above, the row numbers and also the ability to collapse code sections. If you want to know what are all the available options you can have a look here.

Instances of the control

In the sample solution I’ve defined various instances of the control, each one with a different configuration.

The Basic Value instance is declared with the minimal requirements and will allow the user to specify a non typed code string. It will also save and submit the value to the web part component that displays it.

The Initial Value instance shows how it’s possible to define an initial value to the control. When first rendering, it will show a text without any user action needed.

This will still allow the user to change the string inside the panel:

The Language Value instance shows how the code editor adds visual cues when writing code in the panel. In this specific instance the control has the language set to JSON:

It’s also possible to disable the control. To demonstrate this, the Disabled Value instance, shows how the control renders when it’s disabled. Of course, because the control is disabled, it won’t allow any user operation and this means that the user cannot open the panel and have a look at the code.

Sometimes you want the user to be able to see the code but not to make any change, as the Readonly Value instance demonstrates, this is possible.

When clicking on the button on the right (or on the text box) it will display the code editor without any possibility for the user to make changes:

At the time of writing, with the readonly configuration, the buttons will remain clickable even if the user cannot make any changes, but I can expect this to be changed in the future to be more in line with the user allowed actions.

The last instance that I want to cover is the Options Value one. This will demonstrate how the code editor behavior can be changed. In the sample I removed the line numbers, the active line highlight and a couple more options that I will cover in the code section.

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 PropertyFieldCodeEditor control.

To use the control you have to import it in the web part file with the following statement:

import {
  PropertyFieldCodeEditor,
  PropertyFieldCodeEditorLanguages,
} from "@pnp/spfx-property-controls/lib/PropertyFieldCodeEditor";

The PropertyFieldCodeEditorLanguages is imported to specify which language to be set for the language property, it’s not mandatory for using the control.

To enable the control to set the properties of the web part I defined the following interface:

export interface IPnPPropertyCodeEditorWebPartProps {
  basicValue: string;
  initialValue: string;
  languageValue: string;
  disabledValue: string;
  readonlyValue: string;
  optionsValue: string;
}

Inside the web part getPropertyPaneConfiguration function I defined the various control instances.

Basic Value

Starting with the Basic Value instance one:

PropertyFieldCodeEditor("basicValue", {
  label: strings.BasicValueLabel,
  panelTitle: strings.BasicValueFieldPanelTitle,
  properties: this.properties,
  key: "basicValueField",
  onPropertyChange: this.onPropertyPaneFieldChanged,
})

This instance contains all the mandatory property of the control, let’s discover those:

• label: the string to be displayed above the control.
• panelTitle: the string displayed in the top part of the panel.
• properties: these are the web part properties.
• key: a unique identifier for the control instance.
• onPropertyChange: the method to be called when the value of the control changes. To handle you can use the web part onPropertyPaneFieldChanged method.

This minimal configuration doesn’t specify the coding language that you want to support inside the code editor so there are no visual cues.

I won’t cover the above mentioned properties for each of the control instances to avoid redundancy.

Initial Value

This instance of the control shows how to specify a default value. This can be easily achieved using the initialValue property:

PropertyFieldCodeEditor("initialValue", {
  label: strings.InitialValueLabel,
  panelTitle: strings.InitialValueFieldPanelTitle,
  properties: this.properties,
  key: "initialValueField",
  onPropertyChange: this.onPropertyPaneFieldChanged,
  initialValue: "console.log('Hello, world!');",
})

In the code above the default value for the control will be:

console.log('Hello, world!');

Language Value

As said before, it’s possible to instruct the control about which coding language to support. To specify the coding language you have to use the language property:

PropertyFieldCodeEditor("languageValue", {
  label: strings.LanguageValueLabel,
  panelTitle: strings.LanguageValueFieldPanelTitle,
  properties: this.properties,
  key: "languageValueField",
  onPropertyChange: this.onPropertyPaneFieldChanged,
  language: PropertyFieldCodeEditorLanguages.JSON,
})

To specify which language to use you can use the enum PropertyFieldCodeEditorLanguages which, at the time of writing, contains the following values:

• css
• JavaScript
• JSON
• Handlebars
• HTML
• Plain Text
• Sass
• TypeScript
• XML

Disabled Value

To disable the control is enough to set the disabled property to true, as you can see in the following code snippet:

PropertyFieldCodeEditor("disabledValue", {
  label: strings.DisabledValueLabel,
  panelTitle: strings.DisabledValueFieldPanelTitle,
  properties: this.properties,
  key: "disabledValueField",
  onPropertyChange: this.onPropertyPaneFieldChanged,
  language: PropertyFieldCodeEditorLanguages.Sass,
  initialValue: "body {\n background-color: #f0f0f0;\n}",
  disabled: true,
})

Readonly Value

The PropertyFieldCodeEditor control allows to specify various options that I will cover better in the next chapter. In this instance I used the options property to render the control in a read only fashion:

PropertyFieldCodeEditor("readonlyValue", {
  label: strings.ReadonlyValueLabel,
  panelTitle: strings.ReadonlyValueFieldPanelTitle,
  properties: this.properties,
  key: "readonlyValueField",
  onPropertyChange: this.onPropertyPaneFieldChanged,
  language: PropertyFieldCodeEditorLanguages.XML,
  initialValue: `<options>\n\t<option value='1'>Option 1</option>\n\t<option value='2'>Option 2</option>\n</options>`,
  options: {
    readOnly: true,
  },
})

Options Value

As said in the previous chapter, the control offers the ability to change the code editor behavior specifying an object to the options property. This object is of type AceOptions and you can reference to this page to discover all the available supported properties.

In my sample I used the following code:

PropertyFieldCodeEditor("optionsValue", {
  label: strings.OptionsValueLabel,
  panelTitle: strings.OptionsValueFieldPanelTitle,
  properties: this.properties,
  key: "optionsValueField",
  onPropertyChange: this.onPropertyPaneFieldChanged,
  language: PropertyFieldCodeEditorLanguages.TypeScript,
  options: {
    selectionStyle: "line",
    highlightActiveLine: false,
    showLineNumbers: false,
    cursorStyle: "wide",
    wrap: true
  },
})

The above code enables the selection style to line, switch off highlighting the active line, remove the line numbers, change the cursor style to a different style, and enable the text wrapping.

Conclusions

The PropertyFieldCodeEditor is an awesome addition to your web part’s property pane when you want to allow the user to specify code snippets. For example you can enable the user to specify some CSS to be used inside your web part to enable further UI customization. Another example would be allowing the user to specify a JSON to be used as data source for some control binding.

Hope this helps!