APPNETOS is under active development This website and its documentation are being prepared for public launch. Content and features may change.
Select Theme
Loading

Document Picker

A reusable, AJAX-powered foundation for selecting APPNETOS documents with optional search, sorting and pagination.

What is a Document Picker?

The Document Picker is the generic foundation for reusable APPNETOS document selection. It displays collection-backed, optionally searchable, sortable and paginated results, and delivers selected document data to a JavaScript callback. Specialized pickers, including the Group Picker, extend this implementation rather than rebuilding its workflow.

Pickers are independent of the surrounding UI: the calling application may place one inside an offcanvas, modal, sidebar or inline layout.

Lazy loading and AJAX workflow

Rendering the initial picker adds the container and frontend resources, not the complete result list. Calling the JavaScript picker API triggers an AJAX request to the concrete runtime class and its search() method. Further search, sorting and pagination interactions request only the currently required results.

The backend uses Core\Collection\Search and the configured collection to perform paginated queries. The default page size is 10; submitted limits outside 1–100 fall back to 10. This avoids preloading potentially large collections for every embedded picker.

Selecting documents and consuming results

The JavaScript controller is coreAppPickerDocumentPicker. Call pick(pickerId, callbackFunction, excludeIds) when opening a picker. The callback receives one document-data object in single-selection mode or an array of objects in multi-selection mode. The default result templates include the document ID and the configured output fields; they do not serialize every property of the underlying document.

coreAppPickerDocumentPicker.pick('my-document-picker', (documentData) => {
    console.log('Selected document:', documentData);
}, ['already-selected-document-id']);

The picker does not automatically open or close your modal or offcanvas. That UI lifecycle belongs to the application integration.

Configure a concrete picker

Extend CoreApp\Picker\DocumentPicker, provide a concrete collection with getCollection(), and define the displayed, searchable and sortable fields. The base class returns null for its collection; without an override initialization fails. Use getMode() to choose Mode::SINGLE (default) or Mode::MULTI.

protected function getFields(): array
{
    return [
        ['field' => 'name', 'label' => 'Name'],
    ];
}

protected function getSearchFields(): string|array|null
{
    return 'name';
}

protected function getSortFields(): array|null
{
    return [['field' => 'name', 'label' => 'Name']];
}

This is a field-configuration example. The actual collection implementation must be supplied by the application.

Override methods

Override method Purpose
getId(): string Unique DOM/JavaScript identifier. The generic picker generates a random ID; use a stable custom ID when invoking it by name.
getCollection(): BaseCollection|null Required collection source for document retrieval.
getMode(): Mode Single or multiple selection.
getFields(): array Visible columns and fields returned to JavaScript; supports field configuration such as boolean rendering.
getSearchFields(): string|array|null Fields used for optional text search. Null disables search.
getSortFields(): array|null Allowed sort fields; ascending and descending options are derived automatically.
getExcludedDocumentIds(): array Always-excluded document IDs, combined with per-request frontend exclusions.
getBaseTemplate(): string Outer picker template.
getListTemplate(): string AJAX result-list template.
getSingleSelectListTemplate(): string Single-selection result rows.
getMultiSelectListTemplate(): string Multiple-selection result rows.
getFormTemplate(): string Search and sorting form.
getPaginationTemplate(): string Pagination controls.
addTranslations(): void Translation registration customization.
addScriptsAndStyles(): void Frontend asset registration customization.

The public search() method is the annotated AJAX entry point; ordinary integrations should reuse it rather than replace the established request processing.

Exclusions, sorting and performance

A picker can exclude document IDs passed by JavaScript and IDs returned by getExcludedDocumentIds(). The backend merges, normalizes and deduplicates these values and applies the exclusions to the collection query before pagination, preserving correct result totals.

Sort requests are checked against the configured allow-list. Multiple picker instances can coexist on a page as long as their IDs are distinct.

Templates, Bootstrap and translations

The base, list, form, selection and pagination templates are replaceable. Core Apps provide Bootstrap-versioned template variants for supported framework versions, while applications can supply their own designs. Translation resources are already available in 81 languages for Core Apps that require them. Application-specific replacement templates remain the responsibility of the application when changing Bootstrap versions.

Next Steps

Previous

Picker

Explore Picker

Next

Group Picker

Explore Group Picker