CoolCMS API

RegionPickerHandler extends AbstractParameterHandler
in package

FinalYes

Handler of `REGION_PICKER`: a "municipality or postcode" field with a suggest; the alternative to {@see SelectRegionHandler} (a `<select>` for sites with only countries/regions).

The value carrier is the region id as <input type="hidden">, but built as a TextInput, not a HiddenField: HiddenField::addError() puts the error on the form and templates do not render form-level errors, so the "pick a municipality" message would be lost. A TextInput keeps the error on the field and also has an id for the <label>.

Rendering follows the option widget = regionSuggest: the front end Style_1/Style_Filter renders the RegionSuggest component ({control "regionSuggest-<key>"}), the admin _form.latte the picker picker-regionSuggestParam. IMPORTANT: the template must render the carrier; a field that is not rendered is wiped from the database on save.

The value is stored as a normal parameter (extract and applyEntityValue() inherited); the Api splits it into city, postcode and country on save (AdvertRegionAddressTrait). The filter (p[id]=regionId) is built as a region subtree by the list presenter, not the handler (toFilters()).

Table of Contents

Constants

ADMIN_PICKER_KEY  : string = 'regionSuggestParam'
Key of the admin picker configuration (`pickers()['regionSuggestParam']`).
WIDGET  : string = 'regionSuggest'
Control option by which templates render the suggest instead of a bare input.

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>
Active filter badge: the region name instead of the bare id.
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
isValidRegion()  : bool
resolveDefaultValue()  : string|null
Resolves the default of a new field (no entity value).
setupOptions()  : void
toFilters()  : array<string|int, Filter>
Returns no filters: the region subtree (`region.lft/rgt`) needs a node from the database.
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

Constants

ADMIN_PICKER_KEY

Key of the admin picker configuration (`pickers()['regionSuggestParam']`).

public string ADMIN_PICKER_KEY = 'regionSuggestParam'

WIDGET

Control option by which templates render the suggest instead of a bare input.

public string WIDGET = 'regionSuggest'

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]

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

isValidRegion()

public static isValidRegion(mixed $value, callable(int): bool $validator) : bool
Parameters
$value : mixed
$validator : callable(int): bool
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()

Returns no filters: the region subtree (`region.lft/rgt`) needs a node from the database.

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

The list presenter builds it (ParameterTrait::buildRegionSubtreeFilters()). An exact id match would not find the adverts of the municipalities inside a region.

Parameters
$parameterId : int
$urlParams : array<string|int, 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