Taxonomy picker component in the Microsoft Graph Toolkit

Artikkel
02/07/2024

The taxonomy picker is a component that can query the Microsoft Graph API for Taxonomy and render a dropdown control with terms, allowing selection of a single term based on the specified term set id or a combination of the specified term set id and the specified term id.

The component retrieves the first level terms that are present under a specified term set or term. If only the term set ID is provided, it returns the first level terms under that term set. If both the term set ID and term ID are provided, it returns the first-level terms under the specified term.

Note This capability currently supports a single selection of terms coming from the term store.

Example

The following example shows the use of the mgt-taxonomy-picker component to select a term from a term set.

HTML
React

Open this example in mgt.dev.

Properties and attributes

You can use several attributes to change the behavior of the component. The required attribute is term-set-id.

Attribute	Property	Description	Type
term-set-id	termsetId	Mandatory. The ID of the term set to retrieve first level terms from.	String
term-id	termId	Optional. The ID of the term to retrieve first level terms from. If not provided, the function retrieves the first level terms under the term set specified by `term-set-id`. Note that this term must be one of the terms under the term set with ID `term-set-id`.	String
site-id	siteId	Optional. The id of the site where the term set is present. If not specified, the term set is assumed to be at the tenant level.	String
version	version	Optional. API version to use when making the GET request. Default is `beta`.	String
placeholder	placeholder	Optional. The placeholder to use in the combobox. Default value is `Select a term`.	string
locale	locale	Optional. The locale of the terms that need to be displayed. This is useful only when terms have multiple labels in different languages.	String
default-selected-term-id	defaultSelectedTermId	Optional. The id of the term that should be selected by default.	String
position	position	Optional. The position of the dropdown. Can be 'above' or 'below'. Default is `below`	String
disabled	disabled	Optional. Sets whether the taxonomy picker is disabled. When disabled, the user isn't able to search or select terms.	NA
cache-enabled	cacheEnabled	Optional. When set, it indicates that the response from the resource will be cached. Default is `false`.	Boolean
cache-invalidation-period	cacheInvalidationPeriod	Optional. (Number of milliseconds) When set in combination with `cacheEnabled`, the delay before the cache reaches its invalidation period will be modified by this value. Default is `0` and will use the default invalidation period.	Number

The following example changes the behavior of the component to fetch first level child terms of specified term set.

<mgt-taxonomy-picker
  term-set-id="138a652e-7f23-46f6-b480-13da2308c235"
></mgt-taxonomy-picker>

The following example changes the behavior of the component to fetch first level child terms of specified term.

<mgt-taxonomy-picker
  term-set-id="138a652e-7f23-46f6-b480-13da2308c235"
  term-id="a56caeb7-3b7d-4d22-93a9-0232e12905f6"
></mgt-taxonomy-picker>

The following example changes the behavior of the component to fetch the French labels of the first level child terms of specified term.

<mgt-taxonomy-picker
  term-set-id="138a652e-7f23-46f6-b480-13da2308c235"
  term-id="a56caeb7-3b7d-4d22-93a9-0232e12905f6"
  locale="fr-FR"
></mgt-taxonomy-picker>

The following example changes the behavior of the component to fetch first level child terms of specified term set that is present in a specified site.

<mgt-taxonomy-picker
  term-set-id="7889007a-fb0e-449f-b629-dedf63ae53de"
  site-id="contoso.sharepoint.com,0962bcef-48f1-4460-baa8-b7286dcb249b,ba412b3c-951a-4322-ac37-0fe6307b5987"
></mgt-taxonomy-picker>

The following example changes the behavior of the component to fetch first level child terms of specified term set and sets a specified term to be selected by default.

<mgt-taxonomy-picker
  term-set-id="138a652e-7f23-46f6-b480-13da2308c235"
  default-selected-term-id="7ab1d163-f691-4676-88b3-c2d8921b73eb"
></mgt-taxonomy-picker>

CSS custom properties

The mgt-taxonomy-picker component defines the following CSS custom properties for you to provide overrides with.

<mgt-taxonomy-picker
  class="taxonomy-picker"
  term-set-id="138a652e-7f23-46f6-b480-13da2308c235"
></mgt-taxonomy-picker>

.taxonomy-picker {
  --taxonomy-picker-background-color: grey;
  --taxonomy-picker-list-max-height: 200px;
  --taxonomy-picker-background-color: black;
  --taxonomy-picker-placeholder-color: white;
  
}

To learn more, see styling components.

Methods

Method	Description
refresh(force?:boolean)	Call the method to refresh the data. By default, the UI will only update if the data changes. Pass `true` to force the component to update.

Events

Event	When is it emitted	Custom data	Cancelable	Bubbles	Works with custom template
`selectionChanged`	Fired when the user makes a change in selection in the dropdown.	The selected term that will of the type `TermStore.Term`	No	Yes	Yes

For more information about handling events, see events.

Templates

The mgt-taxonomy-picker component supports several templates that you can use to define the look and feel. To specify a template, include a <template> element inside a component and set the data-type to one of the following values.

Data type	Data context	Description
error	The error from Microsoft Graph.	This template is used if there's an error making the request.
loading	N/A	This template is used while the request is being made.
no-data	N/A	This template is used when the request returned no data.

Example template usage

<mgt-taxonomy-picker term-set-id="138a652e-7f23-46f6-b480-13da2308c235">
  <div>Loading template</div>
    <template data-type="loading">
      Loading
    </template>
    <template data-type="no-data">
      <div>No data</div>
    </template>
    <template data-type="error">
      <div>Error</div>
    </template>
  </div>
</mgt-taxonomy-picker>

Microsoft Graph permissions

This component uses the following Microsoft Graph APIs and permissions. For each API called, the user must have at least one of the permissions listed.

Configuration	Permission	API
default	TermStore.Read.All, TermStore.ReadWrite.All	/termStore/sets/{setId}/children
default	TermStore.Read.All, TermStore.ReadWrite.All	/termStore/sets/{setId}/terms/{termId}/children
`site-id` is set	TermStore.Read.All, TermStore.ReadWrite.All	/sites/{site-id}/termStore/sets/{set-id}/children
`site-id` is set	TermStore.Read.All, TermStore.ReadWrite.All	/sites/{site-id}/termStore/sets/{set-id}/terms/{term-id}/children

For more information about permissions, see the Microsoft Graph permissions reference.

Authentication

The control uses the global authentication provider described in the authentication documentation to fetch the required data.

Cache

To enable and configure the cache, use the cacheEnabled and cacheInvalidationPeriod properties. By default, the mgt-taxonomy-picker component doesn't cache any responses.

Object store	Cached data	Remarks
`response`	Complete response retrieved from Microsoft Graph for the terms.

For details, see Caching.

Localization

The control exposes the following variables that can be localized. For details about how to set up localization, see Localizing components.

String name	Default value
comboboxPlaceholder	`Select a term`
loadingMessage	`Loading...`
noTermsFound	`No terms found`
termsetIdRequired	`The termsetId property or termset-id attribute is required`

Jagamisviis: