CoolCMS API

DatetimeHandler extends AbstractParameterHandler
in package

FinalYes

Unified handler of one parameter type covering its whole lifecycle.

  • form building: buildField(), setupOptions(), applyDefault(), extractValue()/extractRows(),
  • URL to form and back: toUrlParams(), fromUrlParams(),
  • database filters: toFilters(),
  • display of the stored value: formatValue().

Each type implements getTypes() and buildField(); the other methods have defaults for single-field scalar types and are overridden as needed.

Instances are stateless and registered in ParameterHandlerRegistry. The mode (form vs. search) is chosen by the caller, who passes the registry the int type (getType() or getSearchType()); a handler serves exactly one type.

Table of Contents

Methods

applyDefault()  : void
applyEntityValue()  : void
Prefills the form field with the entity value; a scalar or array goes to `$key`.
buildField()  : BaseControl
extractRows()  : array<int, array{value: mixed, value2?: ?string}>
Splits the submitted values into rows to persist (one `AdvertParameterRel` per row).
extractValue()  : mixed
Extracts the value from the form for persistence.
formatValue()  : string|object|null
Formats the stored value of a parameter relation for display.
fromUrlParams()  : array<string, mixed>
Converts URL fragments back to defaults for `$form->setDefaults()`.
getActiveValueLabels()  : array<int|string, string>
Returns human-readable labels of the active parameter value, used for the filter badges above the list (`.pactive__chip`).
getParameterLabel()  : string
Returns the label of a parameter or option in the context language.
getTypes()  : array<string|int, int>
hasTranslatedLabel()  : bool
Returns whether the item has a usable label in the current language.
isPersistable()  : bool
resolveDefaultValue()  : string|null
Resolves the default of a new field (no entity value).
setupOptions()  : void
toFilters()  : array<string|int, Filter>
Builds database filters from URL fragments.
toUrlParams()  : array<string|int, mixed>
Converts submitted form values to URL fragments for the redirect.
applyDisplayText()  : string
Applies the display text (`display_text`) of the translation to an already rendered value.
getOptionItems()  : array<int, string>
Returns plain option labels without counts.
getOptionItemsForField()  : Html> : array)
Returns option labels for a form field, with item counts when the module supplied them.
getParameterPlaceholder()  : string|null
getParameterText()  : string|null
resolveDisplayText()  : string|null
resolveOptionLabel()  : string|null
Finds the option (child parameter) by the stored id and returns its translated name.
resolveTranslation()  : ParameterTextInterface|null

Methods

applyEntityValue()

Prefills the form field with the entity value; a scalar or array goes to `$key`.

public applyEntityValue(Form $form, string $key, mixed $value[, bool $force = false ]) : void

Range overrides it to split into {key}_from and {key}_to.

With $force it calls setValue() instead of setDefaultValue(), which is a no-op on a submitted and anchored form (Nette BaseControl::setDefaultValue); without force, new fields revealed by an AJAX category refresh would stay empty. IMPORTANT: use $force only for fields that are not in the submitted POST (see ParameterFieldBuilder::applyEntityDefaultsForNewFields()), otherwise it overwrites the value the user is typing.

Parameters
$form : Form
$key : string
$value : mixed
$force : bool = false

extractRows()

Splits the submitted values into rows to persist (one `AdvertParameterRel` per row).

public extractRows(ArrayHash $values, string $key, ParameterInterface $parameter) : array<int, array{value: mixed, value2?: ?string}>

A scalar becomes one row, an array (multiselect/checkboxlist) one row per item. Range overrides it to value (from) and value2 (to).

Parameters
$values : ArrayHash
$key : string
$parameter : ParameterInterface
Return values
array<int, array{value: mixed, value2?: ?string}>

extractValue()

Extracts the value from the form for persistence.

public extractValue(BaseControl $element, ParameterInterface $parameter) : mixed

Most types return a scalar; multiselect and checkboxlist return an array.

Parameters
$element : BaseControl
$parameter : ParameterInterface

formatValue()

Formats the stored value of a parameter relation for display.

public formatValue(string|null $value, string|null $value2, ParameterInterface $parameter, ParameterRenderContext $context) : string|object|null

Receives the raw value/value2 of AdvertParameterRel (not the entity, so the handler does not depend on the module variant of the relation), the parameter itself (for translation and type) and the render context (language, locale). Returns:

  • string: the formatted cell value,
  • object: a typed value object for a special template (e.g. OpeningHours),
  • null: the row is skipped.

The default implementation covers simple single-value types.

Parameters
$value : string|null
$value2 : string|null
$parameter : ParameterInterface
$context : ParameterRenderContext
Return values
string|object|null

fromUrlParams()

Converts URL fragments back to defaults for `$form->setDefaults()`.

public fromUrlParams(string $key, int $parameterId, array<string|int, mixed> $urlParams) : array<string, mixed>
Parameters
$key : string
$parameterId : int
$urlParams : array<string|int, mixed>

content of $_GET['p'] (key 12 is an int in PHP)

Return values
array<string, mixed> —

map of [formKey => value]

getActiveValueLabels()

Returns human-readable labels of the active parameter value, used for the filter badges above the list (`.pactive__chip`).

public getActiveValueLabels(ParameterInterface $parameter, mixed $value, ParameterFormContext $context) : array<int|string, string>

Returns one label per removable value. The default covers all types: a parameter with options maps the option id to its name, others return the value as text. A type handler may override it (range "from-to", date, etc.).

IMPORTANT: it reads from the already loaded parameter entity (optionsCollection is in the filter includes) and must not issue an extra query.

Parameters
$parameter : ParameterInterface
$value : mixed
$context : ParameterFormContext
Return values
array<int|string, string> —

value => label (the key is what gets removed from the URL)

getParameterLabel()

Returns the label of a parameter or option in the context language.

public getParameterLabel(ParameterInterface $parameter, ParameterFormContext $context) : string

IMPORTANT: the fallback chain must skip an empty string, not only null (?? does not). A translation with an empty name would otherwise win over the default language and the option would render with no name at all on a foreign-language site. A missing row behaves correctly (falls back to the first translation), so "no row" and "empty row" must be told apart. Empty rows are no longer written; this guards data from imports or manual SQL.

Parameters
$parameter : ParameterInterface
$context : ParameterFormContext
Return values
string

getTypes()

public getTypes() : array<string|int, int>
Return values
array<string|int, int> —

ParameterType constants served by this handler

hasTranslatedLabel()

Returns whether the item has a usable label in the current language.

public hasTranslatedLabel(ParameterInterface $parameter, ParameterFormContext $context) : bool

Basis of the rule "hide untranslated items, do not show the default language". The parameter key deliberately does not count as a label: usb is a technical identifier, not a translation, and looks as wrong in a foreign-language filter as the default language.

Parameters
$parameter : ParameterInterface
$context : ParameterFormContext
Return values
bool

resolveDefaultValue()

Resolves the default of a new field (no entity value).

public resolveDefaultValue(ParameterInterface $parameter, string|null $defaultValue, ParameterFormContext $context) : string|null

Receives the parameter default_value (or search_default_value) and may override it; the default implementation returns it unchanged.

Parameters
$parameter : ParameterInterface
$defaultValue : string|null
$context : ParameterFormContext
Return values
string|null

toFilters()

Builds database filters from URL fragments.

public toFilters(int $parameterId, array<int|string, mixed> $urlParams[, bool $matchAll = false ]) : array<string|int, Filter>
Parameters
$parameterId : int
$urlParams : array<int|string, mixed>

content of $_GET['p'] (numeric parameter key is an int in PHP)

$matchAll : bool = false

AND within a facet: a multi-value facet creates N separate ParameterRelFilters (each with its own join, so an implicit AND at top level) instead of one value IN (...) (an OR). Driven by Parameter::getFilterMatchAll().

Return values
array<string|int, Filter>

toUrlParams()

Converts submitted form values to URL fragments for the redirect.

public toUrlParams(string $key, int $parameterId, ArrayHash $values) : array<string|int, mixed>

Returns an associative array merged into $params['p'][]. The key is the parameter id (with a _from/_to suffix for ranges); PHP stores a numeric key as int.

Parameters
$key : string
$parameterId : int
$values : ArrayHash
Return values
array<string|int, mixed>

applyDisplayText()

Applies the display text (`display_text`) of the translation to an already rendered value.

protected applyDisplayText(string $display, array<string, string> $values, int|null $count, ParameterInterface $parameter, ParameterRenderContext $context) : string
  • a text with %value%/%value2% is a standalone sentence that embeds the values ("employs %value% people"); only the text is returned,
  • a text without a placeholder is a suffix after the value ("10 - 30 days").

The plural variant ({1}|[2,4]|...) is chosen by $count (internally %count%); $values carry the named replacements (%value%, %value2%). Without a text (or translation) $display is returned unchanged.

Parameters
$display : string
$values : array<string, string>
$count : int|null
$parameter : ParameterInterface
$context : ParameterRenderContext
Return values
string

getOptionItems()

Returns plain option labels without counts.

protected getOptionItems(ParameterInterface $parameter, ParameterFormContext $context) : array<int, string>

IMPORTANT: the active filter badges (getActiveValueLabels()) take their label from here, which is why counts are added only in getOptionItemsForField(). Otherwise a badge would read "Sony (3)", although it says what is checked, not how many items there are.

Parameters
$parameter : ParameterInterface
$context : ParameterFormContext
Return values
array<int, string>

getOptionItemsForField()

Returns option labels for a form field, with item counts when the module supplied them.

protected getOptionItemsForField(ParameterInterface $parameter, ParameterFormContext $context[, bool $html = true ]) : Html> : array)

Without counts in the context it returns exactly what getOptionItems() does, so adverts and the company catalog are unaffected until they supply counts themselves.

IMPORTANT: pass $html = false for <select>: <option> cannot hold nested markup and the label would be printed with its tags. Checkboxes and radios render the Html label.

An option with count 0 gets the is-empty class; it is greyed out, and hiding it is then a single CSS rule instead of a PHP change.

Parameters
$parameter : ParameterInterface
$context : ParameterFormContext
$html : bool = true
Return values
Html> : array)
On this page

Search results