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.