form-engine/org.octavius.form.control.type.selection/DatabaseControl

DatabaseControl

class DatabaseControl(label: String?, val query: QueryFragment, val displayColumn: String, val idColumn: String = "id", val orderBy: String = displayColumn, val searchFilter: (String) -> QueryFragment?? = null, val pageSize: Long = 10, required: Boolean? = false, dependencies: Map<String, ControlDependency<*>>? = null, actions: List<ControlAction<Int>>? = null) : AsyncPaginatedDropdownControl<Int> , KoinComponent

Kontrolka do wyboru rekordu z bazy danych z listy rozwijanej.

Źródłem jest dowolne zapytanie. Kontrolka owija je podzapytaniem i dokleja wyszukiwanie, sortowanie i stronicowanie, nigdy go nie przepisując - ten sam kontrakt co buildQuery() w report-engine. Joiny, stały filtr czy wyliczany tekst pozycji piszesz więc w SQL-u, a nie w parametrach kontrolki:

"author_id" to DatabaseControl(
    label = Tr.Books.Form.author(),
    query = QueryFragment("SELECT id, name FROM books.authors"),
    displayColumn = "name"
)

Wartością kontrolki jest idColumn wybranego wiersza. Cały wiersz - łącznie z kolumnami, których kontrolka nie pokazuje - trafia przy wyborze do ActionContext.payload, więc akcja może z niego wypełnić inne kontrolki.

Parameters

query

Zapytanie źródłowe. Jego parametry są dołączane do każdego wywołania.

displayColumn

Kolumna wyniku pokazywana jako tekst pozycji.

idColumn

Kolumna wyniku będąca wartością kontrolki.

orderBy

Sortowanie listy, domyślnie po displayColumn. idColumn jest zawsze doklejane na końcu jako rozstrzygnięcie remisów: bez tego stronicowanie przez OFFSET nie jest deterministyczne, a przy doklejaniu kolejnych stron pozycja o powtórzonym tekście na granicy strony mogłaby się pojawić dwa razy albo wcale.

searchFilter

Warunek wyszukiwania dla wpisanego tekstu. Brak lambdy albo null z niej oznacza domyślne displayColumn::text ILIKE %tekst%. Ten sam kształt co buildQuickSearch w report-engine.

pageSize

Liczba pozycji doczytywanych naraz.

Constructors

DatabaseControl

constructor(label: String?, query: QueryFragment, displayColumn: String, idColumn: String = "id", orderBy: String = displayColumn, searchFilter: (String) -> QueryFragment?? = null, pageSize: Long = 10, required: Boolean? = false, dependencies: Map<String, ControlDependency<*>>? = null, actions: List<ControlAction<Int>>? = null)

Properties

actions

private val actions: List<ControlAction<T>>?

private val db: OctaviusClient

debounceMs

protected open val debounceMs: Long = 0

Ile odczekać po ostatnim wpisanym znaku, zanim poleci zapytanie.

dependencies

internal val dependencies: Map<String, ControlDependency<*>>?

displayColumn

private val displayColumn: String

errorManager

protected lateinit var errorManager: ErrorManager

formActionTrigger

protected lateinit var formActionTrigger: FormActionTrigger

formSchema

protected lateinit var formSchema: FormSchema

formState

protected lateinit var formState: FormState

hasStandardLayout

protected val hasStandardLayout: Boolean

hierarchyRole

internal var hierarchyRole: ControlHierarchyRole

Flaga określająca, rolę kontrolki w hierarchii.

idColumn

private val idColumn: String

label

internal val label: String?

orderBy

private val orderBy: String

pageSize

private val pageSize: Long

query

private val query: QueryFragment

required

internal val required: Boolean?

searchFilter

private val searchFilter: (String) -> QueryFragment??

validationOptions

internal val validationOptions: ValidationOptions?

validator

protected open val validator: ControlValidator<Int>

Validator odpowiedzialny za walidację tej kontrolki. Każdy typ kontrolki dostarcza własną implementację (np. StringValidator). Domyślnie pusta implementacja

Functions

buildSearchFilter

private fun buildSearchFilter(searchQuery: String): QueryFragment

convertToResult

protected open fun convertToResult(controlContext: ControlContext, state: ControlState<*>): ControlResultData

Konwertuje wewnętrzny stan kontrolki (ControlState) na wynik do zapisu (ControlResultData). Może być przesłonięta dla niestandardowych konwersji (np. w RepeatableControl).

copyInitToValue

internal open fun copyInitToValue(value: Int): Int

Tworzy głęboką kopię wartości początkowej dla bieżącej wartości. Kluczowe dla typów mutowalnych (np. List), aby zmiany w value nie wpływały na initValue.

Display

@Composable

protected open override fun Display(controlContext: ControlContext, controlState: ControlState<Int>, isRequired: Boolean)

Abstrakcyjna metoda renderowania specyficznego interfejsu kontrolki. Każdy konkretny typ kontrolki (np. StringControl) musi ją zaimplementować.

DisplayFieldErrors

@Composable

protected fun DisplayFieldErrors(controlContext: ControlContext)

Pomocnicza funkcja renderująca błędy walidacji dla tej kontrolki.

executeActions

protected fun executeActions(controlContext: ControlContext, newValue: Int?, scope: CoroutineScope, payload: Any? = null)

Wykonuje zdefiniowane akcje dla tej kontrolki, zazwyczaj po zmianie wartości.

executeInitActions

internal fun executeInitActions(controlContext: ControlContext, currentValue: Int?, scope: CoroutineScope)

getKoin

open fun getKoin(): Koin

getResult

internal fun getResult(controlContext: ControlContext, state: ControlState<*>): ControlResultData

Pobiera wynik kontrolki (wartość bieżącą i początkową) do dalszego przetwarzania. Jeśli kontrolka jest niewidoczna, jej currentValue jest ustawiane na null.

initializeControlLifecycle

internal open fun initializeControlLifecycle(formState: FormState, formSchema: FormSchema, errorManager: ErrorManager, formActionTrigger: FormActionTrigger)

Ustawia referencje do komponentów formularza. Jest to drugi etap inicjalizacji kontrolki, wywoływany przez FormHandler. Daje dostęp do globalnego stanu, schemy i managera błędów. Dodatkowo umożliwia wykonanie dodatkowych kroków inicjalizacyjnych wymaganych przez określone kontrolki

LoadingIndicator

@Composable

private fun LoadingIndicator()

Komponent renderujący wskaźnik ładowania.

loadPage

protected open suspend override fun loadPage(searchQuery: String, page: Long): DropdownPage<Int>

Podklasy implementują tę metodę, aby dostarczyć dane dla konkretnej strony. Użycie suspend jest kluczowe dla operacji asynchronicznych.

MenuContent

@Composable

private fun MenuContent(options: List<DropdownOption<T>>, isRequired: Boolean, isLoadingFirstPage: Boolean, isLoadingMore: Boolean, errorMessage: String?, onOptionSelected: (DropdownOption<T>?) -> Unit)

Komponent renderujący główną zawartość menu.

OptionsList

@Composable

private fun OptionsList(options: List<DropdownOption<T>>, isRequired: Boolean, onOptionSelected: (DropdownOption<T>?) -> Unit)

Komponent renderujący listę opcji do wyboru.

registerChildrenInGlobalMap

internal open fun registerChildrenInGlobalMap(controlContext: ControlContext): Map<String, Control<*>>

Funkcja do rejestracji dzieci na globalnej mapie Zawiera referencje do kontrolek zdefiniowanych w kontrolce posiadającej własne

Render

@Composable

internal fun Render(controlContext: ControlContext, controlState: ControlState<*>)

Renderuje kontrolkę w interfejsie użytkownika. Ta metoda jest publicznym API dla FormScreen. Obsługuje logikę widoczności.

RenderMenuItems

@Composable

protected open override fun ColumnScope.RenderMenuItems(controlContext: ControlContext, scope: CoroutineScope, controlState: ControlState<Int>, menuScrollState: ScrollState, closeMenu: () -> Unit)

Podklasy muszą zaimplementować tę metodę, aby wyrenderować zawartość menu rozwijanego.

resolveDisplayText

protected open suspend override fun resolveDisplayText(value: Int): String?

Wołane raz na wartość, poza renderowaniem, a wynik zapisuje się w ControlState.displayText.

SearchField

@Composable

private fun SearchField(searchQuery: String, onQueryChange: (String) -> Unit)

Komponent renderujący pole wyszukiwania wewnątrz menu.

setInitValue

internal open fun setInitValue(controlContext: ControlContext, value: Any?): ControlState<Int>

Ustawia początkową wartość kontrolki i tworzy jej stan (ControlState).

validateControl

internal fun validateControl(controlContext: ControlContext, state: ControlState<*>)

Uruchamia proces walidacji dla tej kontrolki przy użyciu przypisanego walidatora.