com.broadleafcommerce.metadata.dsl.core.extension.fields

Interface LookupField<F extends LookupField<F>>

All Superinterfaces:

Comparable<F>, Component<F>, Copyable<F>, Dependent<F>, Field<F>, Filterable<F>, FormComponent<F>, Serializable, Trackable<F>

All Known Implementing Classes:

DefaultLookupField

public interface LookupField<F extends LookupField<F>>
extends Filterable<F>, Dependent<F>, Field<F>, Trackable<F>

Represents the metadata for a FieldTypes.LOOKUP field. A lookup field is useful when the user needs to be able to choose between a number of externally sourced options.

Author:

Nick Crum (ncrum)

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	LookupField.Attributes
static class	LookupField.EndpointTypes
static class	LookupField.SelectionTypes This enum represents the way in which the lookup selections are persisted within the form state.
static class	LookupField.ViewTypes

Nested classes/interfaces inherited from interface com.broadleafcommerce.metadata.dsl.core.extension.Dependent

Dependent.DependentFieldsList

Method Summary

Modifier and Type	Method and Description
default Optional<Endpoint<?>>	findHydrateEndpoint()
default Optional<LookupFieldModal<?>>	findModal() Finds the metadata for the LookupField.ViewTypes.LOOKUP_MODAL configured for this lookup.
default Optional<PageableEndpoint<?>>	findReadEndpoint()
default Endpoint<?>	getHydrateEndpoint()
default PageableEndpoint<?>	getReadEndpoint()
default F	hydrateEndpoint(Endpoint<?> endpoint) Configures the hydration endpoint for the lookup.
default F	hydrateEndpoint(UnaryOperator<Endpoint<?>> fn) Configures the hydration endpoint for the lookup.
default F	hydrateScope(String scope) Configures hydrateEndpoint(UnaryOperator) url.
default F	hydrateUrl(String url) Configures hydrateEndpoint(UnaryOperator) url.
default F	hydrateUrl(String url, String scope) Configures hydrateEndpoint(UnaryOperator) url and scope.
default boolean	isSearchable()
default F	labelKey(String labelKey) Sets the name of the label key.
default F	loadingMessage(String loadingMessageKey) Configure the message to be displayed while the lookup is loading it's options.
default F	modalComponent(String modalComponent) Sets the name of the React component that will be used for rendering the modal search.
default F	modalSearch(UnaryOperator<LookupFieldModal<?>> fn) Configure this lookup with a modal for more advanced searching.
default F	modalToggleLabel(String modalLabelKey) Configures the label for the modal search toggle.
default F	multi() Configures this lookup to support multi-selection.
default F	multi(boolean isMulti) Configures whether or not the lookup supports multi-selection.
default F	noOptionsMessage(String noOptionsMessageKey) Configure the message to be displayed when the lookup finds no options.
default F	notModalSearch() Disables modal support and remove the Advanced button from the lookup field.
default F	notMulti() Configures this lookup to not support multi-selection.
default F	notSearchable() Configures the lookup to not be searchable.
default F	optionSelection() Configures the lookup with the LookupField.SelectionTypes.OPTION selection type.
default F	readEndpoint(PageableEndpoint<?> endpoint) Configure the read endpoint for the lookup.
default F	readEndpoint(UnaryOperator<PageableEndpoint<?>> fn) Configure the read endpoint for the lookup.
default F	readScope(String scope) Configures readEndpoint(UnaryOperator) scope.
default F	readUrl(String url) Configures readEndpoint(UnaryOperator) url.
default F	readUrl(String url, String scope) Configures readEndpoint(UnaryOperator) url with scope
default F	removeSelectionTransforms() Remove any existing transformations added by transformSelection(com.broadleafcommerce.metadata.dsl.core.Mapping<?>...).
default F	searchable() Configures the lookup to be searchable.
default F	searchable(boolean isSearchable) Configures the lookup to be searchable or not
default F	searchableDefaults() Configures the lookup to be searchable and configures the endpoint to map over the default `q` and `cq` parameters.
default F	selectComponent(String selectComponentName) Sets the name of the React component that will be used for rendering the select input.
default F	selectionType(String selectionType) Sets the LookupField.Attributes.SELECTION_TYPE for this lookup.
default F	transformSelection(List<Mapping<?>> mappings) Configure a set of Mapping to transform the option the user selects before the form state is updated.
default F	transformSelection(Mapping<?>... mappings) Configure a set of Mapping to transform the option the user selects before the form state is updated.
default F	transformSelection(UnaryOperator<List<Mapping<?>>> fn) Configure a set of Mapping to transform the option the user selects before the form state is updated.
default F	valueKey(String valueKey) Sets the name of the value key.
default F	valueSelection() Configures the lookup with the LookupField.SelectionTypes.VALUE selection type.

Methods inherited from interface com.broadleafcommerce.metadata.dsl.core.extension.Filterable

implicitFilter, implicitFilters, implicitFilters

Methods inherited from interface com.broadleafcommerce.metadata.dsl.core.extension.Dependent

clearDependentFields, dependentField, dependentFields, parentIdField

Methods inherited from interface com.broadleafcommerce.metadata.dsl.core.Field

decorated, defaultValue, getDefaultValue, getName, getPlaceholder, getRequiredMessage, getValidationSchema, isReadOnly, isRequired, isShowInQueryBuilder, name, notReadOnly, notRequired, placeholder, placeholder, readOnly, readOnly, required, required, required, required, requiredMessage, requiredMessage, setDefaultValue, setName, setPlaceholder, setReadOnly, setRequired, setRequiredMessage, setShowInQueryBuilder, setValidationSchema, validationMethod, validationSchema, validationSchema

Methods inherited from interface com.broadleafcommerce.metadata.dsl.core.FormComponent

getHelpText, getHint, getTooltip, helpText, helpText, hidden, hidden, hint, hint, isHidden, notHidden, setHelpText, setHidden, setHint, setTooltip, tooltip, tooltip

Methods inherited from interface com.broadleafcommerce.metadata.dsl.core.Component

addAction, addAction, addComponent, addEndpoint, addEndpoint, apply, attribute, augmentationKey, classifier, clearConditionals, clearEndpoints, conditional, conditionals, description, description, findAction, findAction, findActions, findAttribute, findComponent, findComponent, findComponents, findEndpoint, findEndpoint, findEndpoints, get, get, getAction, getAction, getActions, getActionsList, getAttribute, getAttribute, getAttributes, getAugmentationKey, getClassifier, getComponent, getComponent, getComponents, getComponentsList, getConditionals, getDescription, getEndpoint, getEndpoint, getEndpoints, getEndpointsList, getId, getLabel, getOrder, getScope, getType, hasAction, hasAttribute, hasComponent, hasEndpoint, id, isAugmentable, isTranslatable, label, label, notTranslatable, order, removeAction, removeAttribute, removeComponent, removeEndpoint, scope, self, setActions, setAttributes, setAugmentationKey, setClassifier, setComponents, setConditionals, setDescription, setEndpoints, setId, setLabel, setOrder, setScope, setTranslatable, setType, translatable, translatable, type

Methods inherited from interface java.lang.Comparable

compareTo

Methods inherited from interface com.broadleafcommerce.metadata.dsl.core.Copyable

copy

Methods inherited from interface com.broadleafcommerce.metadata.dsl.core.extension.Trackable

catalogTrackable, notCatalogTrackable, notSandboxTrackable, sandboxTrackable

Method Detail

readEndpoint

default F readEndpoint(PageableEndpoint<?> endpoint)

Configure the read endpoint for the lookup. This endpoint tells the lookup where it can go to retrieve the options the user chooses from. This endpoint is a PageableEndpoint and supports different paging strategies.

Parameters:

endpoint - the endpoint

Returns:

this

readEndpoint

default F readEndpoint(UnaryOperator<PageableEndpoint<?>> fn)

Configure the read endpoint for the lookup. This endpoint tells the lookup where it can go to retrieve the options the user chooses from. This endpoint is a PageableEndpoint and supports different paging strategies.

Parameters:

fn - function to configure the endpoint

Returns:

this

readUrl

default F readUrl(String url)

Configures readEndpoint(UnaryOperator) url.

Returns:

this

readScope

default F readScope(String scope)

Configures readEndpoint(UnaryOperator) scope.

Returns:

this

readUrl

default F readUrl(String url,
                  String scope)

Configures readEndpoint(UnaryOperator) url with scope

Returns:

this

getReadEndpoint

default PageableEndpoint<?> getReadEndpoint()

Returns:

the read endpoint

findReadEndpoint

default Optional<PageableEndpoint<?>> findReadEndpoint()

Returns:

an optional with read endpoint, or empty

hydrateEndpoint

default F hydrateEndpoint(Endpoint<?> endpoint)

Configures the hydration endpoint for the lookup. This endpoint tells the lookup where to can go to retrieve the hydrated option for the current value. This endpoint is used when the component mounts to hydrate the option associated with the stored value.

This is only necessary when only the option value is being stored in the property as when configured with a valueSelection(). This may be necessary in certain optionSelection() situations when the option being stored is heavily transformed by transformSelection(Mapping[]).

Parameters:

endpoint - the hydrate endpoint

Returns:

this

hydrateEndpoint

default F hydrateEndpoint(UnaryOperator<Endpoint<?>> fn)

Configures the hydration endpoint for the lookup. This endpoint tells the lookup where to can go to retrieve the hydrated option for the current value. This endpoint is used when the component mounts to hydrate the option associated with the stored value.

This is only necessary when only the option value is being stored in the property as when configured with a valueSelection(). This may be necessary in certain optionSelection() situations when the option being stored is heavily transformed by transformSelection(Mapping[]).

Parameters:

fn - a function to configure the hydrate endpoint

Returns:

this

hydrateUrl

default F hydrateUrl(String url)

Configures hydrateEndpoint(UnaryOperator) url.

Returns:

this

hydrateScope

default F hydrateScope(String scope)

Configures hydrateEndpoint(UnaryOperator) url.

Returns:

this

hydrateUrl

default F hydrateUrl(String url,
                     String scope)

Configures hydrateEndpoint(UnaryOperator) url and scope.

Returns:

this

getHydrateEndpoint

default Endpoint<?> getHydrateEndpoint()

Returns:

the hydrate endpoint

findHydrateEndpoint

default Optional<Endpoint<?>> findHydrateEndpoint()

Returns:

an optional with hydrate endpoint, or empty

searchable

default F searchable(boolean isSearchable)

Configures the lookup to be searchable or not

Parameters:

isSearchable - whether or not searchable

Returns:

this

searchable

default F searchable()

Configures the lookup to be searchable. This allows the user to type text into the select in order to filter the results. If using an API with the standard text query parameters, then use searchableDefaults().

Returns:

this

isSearchable

default boolean isSearchable()

Returns:

whether or not this lookup is configured as searchable

searchableDefaults

default F searchableDefaults()

Configures the lookup to be searchable and configures the endpoint to map over the default `q` and `cq` parameters. This is compatible with the standard pattern for searchable endpoints. If the endpoint being searched against supports a non-standard pattern, then searchable(boolean) should be used and the readEndpoint(UnaryOperator) configured with the parameters.

Returns:

this

notSearchable

default F notSearchable()

Configures the lookup to not be searchable. This is the default if searchable() is not used.

Returns:

this

multi

default F multi(boolean isMulti)

Configures whether or not the lookup supports multi-selection.

Returns:

this

multi

default F multi()

Configures this lookup to support multi-selection. This is useful for situations where the user should be able to select one or more options.

For configurations where valueSelection() is chosen, the selected options will have their values persisted in an array.

For configurations where optionSelection() is chosen, the selected options will themselves be stored in an array.

Returns:

this

notMulti

default F notMulti()

Configures this lookup to not support multi-selection.

Returns:

this

selectionType

default F selectionType(String selectionType)

Sets the LookupField.Attributes.SELECTION_TYPE for this lookup. This attribute drives the way in which the option chosen by the user is persisted within the form state.

Parameters:

selectionType - the modal component name

Returns:

this

See Also:

for more details on the different selection types, for behavior to select only the option's value, for behavior to select the entire option

valueSelection

default F valueSelection()

Configures the lookup with the LookupField.SelectionTypes.VALUE selection type. This engages behavior that will cause only the selected option's value to be stored within the form state for this field.

Note, the value of the selected option is driven by the valueKey(String), which defaults to "id".

Returns:

this

optionSelection

default F optionSelection()

Configures the lookup with the LookupField.SelectionTypes.OPTION selection type. This engages behavior that will cause the entire selected option to be stored within the form state for this field.

Note, the option that is stored may be different from the data selected if this lookup is configured with transformSelection(Mapping[]), as that transforms the selected value before persistence.

Returns:

this

transformSelection

default F transformSelection(Mapping<?>... mappings)

Configure a set of Mapping to transform the option the user selects before the form state is updated. For LookupField.SelectionTypes.OPTION, this can be used to transform the chosen option into a new structure. For LookupField.SelectionTypes.VALUE, this can be used to map over additional properties from the chosen option outside of the option's value.

Returns:

this

transformSelection

default F transformSelection(List<Mapping<?>> mappings)

Configure a set of Mapping to transform the option the user selects before the form state is updated. For LookupField.SelectionTypes.OPTION, this can be used to transform the chosen option into a new structure. For LookupField.SelectionTypes.VALUE, this can be used to map over additional properties from the chosen option outside of the option's value.

Returns:

this

transformSelection

default F transformSelection(UnaryOperator<List<Mapping<?>>> fn)

Configure a set of Mapping to transform the option the user selects before the form state is updated. For LookupField.SelectionTypes.OPTION, this can be used to transform the chosen option into a new structure. For LookupField.SelectionTypes.VALUE, this can be used to map over additional properties from the chosen option outside of the option's value.

Returns:

this

removeSelectionTransforms

default F removeSelectionTransforms()

Remove any existing transformations added by transformSelection(com.broadleafcommerce.metadata.dsl.core.Mapping<?>...).

labelKey

default F labelKey(String labelKey)

Sets the name of the label key. Defaults to "name". It can contain the template to create more complicated labels. * For example to display the label like `Name (id)` the template like `${name} - (${id})` can be used.

Parameters:

labelKey - the label key

Returns:

this

valueKey

default F valueKey(String valueKey)

Sets the name of the value key. Defaults to "id".

Parameters:

valueKey - the label key

Returns:

this

loadingMessage

default F loadingMessage(String loadingMessageKey)

Configure the message to be displayed while the lookup is loading it's options.

Parameters:

loadingMessageKey - the label key

Returns:

this

noOptionsMessage

default F noOptionsMessage(String noOptionsMessageKey)

Configure the message to be displayed when the lookup finds no options.

Parameters:

noOptionsMessageKey - the label key

Returns:

this

selectComponent

default F selectComponent(String selectComponentName)

Sets the name of the React component that will be used for rendering the select input. This is generally used for more advanced lookups that require a more complicated interface.

Parameters:

selectComponentName - the modal component name

Returns:

this

modalComponent

default F modalComponent(String modalComponent)

Sets the name of the React component that will be used for rendering the modal search. This is generally used for more advanced lookups that require a more complicated interface.

Note, you must configure the modal component metadata using modalSearch(java.util.function.UnaryOperator<com.broadleafcommerce.metadata.dsl.core.extension.fields.LookupFieldModal<?>>)

Parameters:

modalComponent - the modal component name

Returns:

this

modalToggleLabel

default F modalToggleLabel(String modalLabelKey)

Configures the label for the modal search toggle.

Note, you must configure the modal component metadata using modalSearch(java.util.function.UnaryOperator<com.broadleafcommerce.metadata.dsl.core.extension.fields.LookupFieldModal<?>>)

Parameters:

modalLabelKey - the message key

Returns:

this

findModal

default Optional<LookupFieldModal<?>> findModal()

Finds the metadata for the LookupField.ViewTypes.LOOKUP_MODAL configured for this lookup.

Note, the metadata this retrieves can be configured using modalSearch(java.util.function.UnaryOperator<com.broadleafcommerce.metadata.dsl.core.extension.fields.LookupFieldModal<?>>).

Returns:

the optional with lookup field modal or empty

modalSearch

default F modalSearch(UnaryOperator<LookupFieldModal<?>> fn)

Configure this lookup with a modal for more advanced searching. This will result in an additional toggle button being rendered that, upon clicking, will provide the user with a modal that includes a filterable list grid of options. This is primarily used in instances where the text search within the lookup select is not sufficient on its own.

Note, you can use modalComponent(java.lang.String) to configure a custom React component for the modal, or modalToggleLabel(java.lang.String) to configure the label for the modal toggle button. Lastly, modal search can be disabled again using notModalSearch().

Parameters:

fn - a function that further configures the search modal

Returns:

this

notModalSearch

default F notModalSearch()

Disables modal support and remove the Advanced button from the lookup field.

Returns:

this