Package 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)

  • Method Details

    • 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

    • creatable

      default F creatable()
      Configures the lookup as creatable.
      Returns:
      this

    • creatable

      default F creatable(boolean isCreatable)
      Configures whether the lookup is creatable.
      Returns:
      this

    • 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

    • showModalSearchUnderLookup

      default F showModalSearchUnderLookup()

    • showModalSearchUnderLookup

      default F showModalSearchUnderLookup(boolean showModalUnderLookup)

    • 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:

    • 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 {@link "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 {@link "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

    • removeShowModalSearchUnderLookup

      default F removeShowModalSearchUnderLookup()

    • catalogSelector

      default F catalogSelector()
      Configure the catalog selector to be displayed next to the lookup field in order to hydrate the context with the necessary catalog id parameters for lookup requests.
      Returns:
      this

    • removeCatalogSelector

      default F removeCatalogSelector()
      Remove the catalog selector from the lookup field.
      Returns:
      this