Field picker

Usage

The store

The FieldPicker uses seperate store for its state. To allow for multiple FieldPickers with seperate stores, createFieldPickerStore() is used to create each store. This function must be used to create a store before the FieldPicker is used.

The external store is used to avoid having to rebuild the field tree everytime the FieldPicker is mounted, the store is persisted across renders. As a consequence, you need to build the store using the buildFieldTree function as a part of the state management of your app, for instance when the account changes. The store expects metadata v2 field and group definitions and can be set up like this:

Components

This will render a FieldPicker with no selected fields and using default components.

Spying

Most likely you will want to know what is going on inside the store, or update your own application state when things change. We provide a Hook for this purpose.

WARNING: you can create a loop using this, as initialSelectedFields is set using an action, which causes the hook to be called, which causes a re-render. initialSelectedFields should not be re-created on each render, like it is in the example above.

Instead either get initialSelectedFields from outside the component or use an effect hook to set it once.

The FieldPicker above will console log actions to demonstrate.

FieldPicker props

store

Store used to track the FieldPicker state.

initialSelectedFields

To reset the selected fields in the picker on mount set the initialSelectedFields prop to an array containing field ids.

virtualisationThreshold

When the number of fields in a tree group is larger than this number, the fields will be rendered using a virtualized window. This allows for really large groups, but has a tradeoff with potentially double scrollbars. The default is 500.

components

The FieldPicker accepts custom components:

The FieldListItem component will receive two props:

• field - by default a FieldPickerField object. This can be overridden using the getField prop; more on that below
• onRemove(fieldId) - function that should be called when a field should be removed from the list

The FieldListToolbar has no props.

getField

You can pass in a function that will be called to find the field that should be displayed in the field list. The result of this function will be passed to the FieldListItem component as the field prop.

Custom group and field objects

Internally the FieldPicker maintains structures containing custom group and field definitions. These have more properties than the vanilla versions.

Group

• id
• name
• parent - the id of the parent group
• children - also a map of groups
• fields - a map of the fields in this group
• level - indicates how far down (up?) the tree we are
• path - array of the group ids, e.g. [‘google’, ‘google-goals’]
• pathName - path as text, e.g. Google > GA Goals
• visibleFieldCount - recursively count fields that should be shown
• selectedFieldCount - recursively count fields that are currently selected

Field

• id
• name
• hidden - if the field is hidden in the tree view.
• selected - if the field is selected. The field will be visible in the tree view, even if hidden.
• selectable - if the field can be selected. Non-selectable are not shown in the tree view but in search results.
• standard - if true this field can not be removed. The field will be included in the ‘standard fields’ group.
• matches - if the field matches the current search & filter
• group - id of the group the field belongs to
• isDim - needed for the ‘all | metrics | dimensions’ filter
• … and the usual field properties, needed for rendering properly

Field states

A field is shown in the tree if it is:

• not hidden and selectable and matches the filter
• or selected

A field is shown in search results if it is:

• matches the search & filter

For example optional (unavailable) are hidden and selectable, formula metrics are hidden and not selectable. Both are visible when searching but not in the tree. Formula metrics cannot not be selected, even when found.