spfx-ootb-fields

IMPORTANT UPDATE: this package was included in PnP React Controls package. Please, use PnP React Controls to get latest and greatest of Fields Controls as well.

This repository contains a set of React components that can be used in SPFx Field Customizers to provide rendering of the fields similar to out of the box experience. Additional benefit is ability to set custom css classes and styles to the component. Related UserVoice requests: https://sharepoint.uservoice.com/forums/329220-sharepoint-dev-platform/suggestions/18810637-access-to-re-use-modern-field-render-controls https://sharepoint.uservoice.com/forums/329220-sharepoint-dev-platform/suggestions/31530607-field-customizer-ability-to-call-ootb-render-meth

Getting started

Installation

To get started you need to install this package to your project and also dependency package @microsoft/sp-dialog.

Enter the following commands to install dependencies to your project:

npm i spfx-ootb-fields --save
npm i @microsoft/sp-dialog --save

Configuration

Once the package is installed, you will have to configure the resource file of the property controls to be used in your project. You can do this by opening the config/config.json and adding the following line to the localizedResources property:

"OotbFieldsStrings": "./node_modules/spfx-ootb-fields/lib/loc/{locale}.js"

Usage

The main scenario to use this package is to import FieldRendererHelper class and to call getFieldRenderer method. This method returns a Promise with a proper field renderer (Promise<JSX.Element>) based on field's type. It means that it will automatically select proper component that should be rendered in this or that field. This method also contains logic to correctly process field's value and get correct text to display (for example, Friendly Text for DateTime fields). As the method returns Promise it should be called in one of React component lifecycle methods, for example, componentWillMount that will occur before render. The resulting field renderer could be saved in the element's state and used later in render method. Here is an example on how it can be used inside custom Field Customizer component (.tsx file):

export interface IOotbFieldsState {
  fieldRenderer?: JSX.Element;
}

//...

@override
  public componentWillMount() {
    FieldRendererHelper.getFieldRenderer(this.props.value, {
      className: this.props.className,
      cssProps: this.props.cssProps
    }, this.props.listItem, this.props.context).then(fieldRenderer => {
      this.setState({
        fieldRenderer: fieldRenderer
      });
    });
  }

public render(): React.ReactElement<{}> {
    return (
      <div className={styles.cell}>
        {this.state.fieldRenderer}
      </div>
    );
  }

Additionally, any of included components can be used by itself.

Controls

Here is a list of the controls included in the package with a description which field types are covered with the specific control. All controls contain next common properties in React props object: cssProps?: React.CSSProperties - CSS properties to apply to the renderer className?: ICssInput - CSS classes to apply to the renderer

| Control | Props | Fields Covered | Comments | | --- | --- | --- | --- | | FieldAttachmentsRenderer | count?: number - amount of attachments | Attachments | Renders Clip icon if there are attachments for the current list item | | FieldDateRenderer | text?: string - text to be rendered | Date and Time | Renders date and time value as simple text | | FieldFileTypeRenderer | path: string - document pathisFolder?: boolean - true if the icon should be rendered for a folder, not file | DocIcon | Renders an icon based on the extension of the current document. Office UI Fabric icons font is used to render the icons | | FieldLookupRenderer | lookups: ISPFieldLookupValue[] - lookup valuesdispFormUrl?: string - url of Display form for the list that is referenced in the lookuponClick?: (args: ILookupClickEventArgs) => {} - custom event handler of lookup item click. If not set the dialog with Display Form will be shown | Lookup (single and multi) | Renders each referenced value as a link on a separate line. Opens popup with Display Form when the link is clicked | | FieldNameRenderer | text?: string - text to displayisLink: boolean - if the Name should be rendered as linkfilePath?: string - path to the documentisNew?: boolean - true if the document is newhasPreview?: boolean - true if the document type has preview (true by default)onClick?: (args: INameClickEventArgs) => {} - custom handler for link click. If not set link click will lead to rendering document preview | Document's Name (FileLeafRef, LinkFilename, LinkFilenameNoMenu) | Renders document's name as a link. The link provides either preview (if it is available) or direct download. Additionally, new documents are marked with "Glimmer" icon | | FieldTaxonomyRenderer | terms: ITerm[] - terms to display | Managed Metadata | Renders each term on a separate line | | FieldTextRenderer | text?: string - text to displayisSafeForInnerHTML?: boolean - true if props.text can be inserted as innerHTML of the componentisTruncated?: boolean - true if the text should be truncated | Single line of text; Multiple lines of text; Choice (single and multi); Yes/No; Integer; Counter; Number; Currency; also used as a default renderer for not implemented fields | Renders field's value as a simple text or HTML | | FieldTitleRenderer | text?: string - text to displayisLink?: boolean - true if the Title should be rendered as linkbaseUrl?: string - web urllistId?: string - list idid?: number - item idonClick?: (args: ITitleClickEventArgs) => {} - custom title click event handler. If not set Display form for the item will be displayed | List Item's Title (Title, LinkTitleNoMenu, LinkTitle) | The control renders title either as a simple text or as a link on the Dislpay Form. Additional actions like Share and Context Menu are not implemented | | FieldUrlRenderer | text?: string - text to displayurl?: string - urlisImageUrl?: boolean - true if the field should be rendered as an image | Hyperlink or Image; URL field from Links List | Renders either link or image | | FieldUserRenderer | users?: IPrincipal[] - users/groups to be displayedcontext: IContext - customizer's context | People and Group | Renders each referenced user/group as a link on a separate line. Hovering the link for users (not groups) leads to opening of Persona control. |

Utilities Classes

Here is a list of Utilities classes and public methods that are included in the package and could be also helpful:

Additional Information

The repository also contains Field Customizer to test the functionality

Debug Url

?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&fieldCustomizers={"Percent":{"id":"57ebd944-98ed-43f9-b722-e959d6dac6ad"}}

Release Notes

| Version | Description | | ------- | ----------- | | 1.0.4 | First stable release with all needed functionality | | 1.1.0 | window.g_listData reference is completely removedSPHelper.getFieldSchemaXmlByTitleOrInternalName is replaced with SPHelper.getFieldSchemaXmlByIdFieldRenderer.getFieldRenderer is now asynchronous and shouldn't be called in render method of Field Customizer | | 1.2.0 | All Field Controls names were prefixed with Field. As example, FieldDateRenderer instead of DateRendererHyperlink or image rendering in Image mode is fixedLookup item display dialog is fixed |

Contribution

Please, feel free to report any bugs or improvements for the repo. If you're going to add a PR please, reference dev branch instead of master.