CoolCMS API

RegionSuggest extends BaseComponent
in package
uses InitTrait, SignalTrait

FinalYes

"City or postcode" field: region suggester.

Shared front end component: the host form embeds it as a Multiplier named after the form control (regionSuggest-parameter_34) and passes it the value carrier. The component renders a wrapper in the contract of the existing picker.js (data-picker, data-picker-suggest, data-picker-input, data-picker-display, data-picker-map-*) and serves the suggest! signal.

The carrier value is region_id. The server splits city, postcode and country on save (Api AdvertRegionAddressTrait); data-picker-map-* is only a preview.

Table of Contents

Constants

SUGGEST_CACHE_SECONDS  : int = 3600
The response depends only on `q`, the language and the field configuration, not on the session, so the browser HTTP cache applies. `private`, not `public`: the front end response carries the session `Set-Cookie` and a shared cache (CDN/proxy) would hand it to other visitors.

Properties

$container  : Container
$routerDispatcher  : RouterDispatcher
$translator  : ITranslator
$appContext  : AppContext
$componentParameters  : array<string, mixed>
$currencyContext  : CurrencyContext|null
$deviceDetector  : DeviceDetector|null
$languageContext  : LanguageContext|null
$localizationContext  : LocalizationContext|null
$settingContext  : SettingContext
$themeContext  : ThemeContext|null
$translatorDomain  : string|null
$fieldMap  : array<string, string>
Item data key (`city`, `zip`, `country`) mapped to the name of a sibling form control that `picker.js` prefills after selection (`data-picker-map-*`). Preview only.
$leafOnly  : bool
Only leaves of the municipality type (advert form).
$minLevel  : int
Lowest tree level offered (1 = country too, 2 = from region).
$placeholderKey  : string|null
Translation key of the own field placeholder (relative to the component domain); `null` = by variant (`placeholder` / `filterPlaceholder`). The watchdog also offers region and district, hence its own text.
$regionManager  : RegionManager

Methods

__call()  : mixed
Dispatches `renderXyz()` to `render('Xyz', ...$args)`.
__construct()  : mixed
createComponent()  : IComponent|null
getAppContext()  : AppContext
getComponentParameter()  : mixed
Returns a component parameter, or null when it is not set.
getContainer()  : Container
getCurrencyContext()  : CurrencyContext|null
getLanguageContext()  : LanguageContext|null
getLocalizationContext()  : LocalizationContext|null
getRouterDispatcher()  : RouterDispatcher
getSettingContext()  : SettingContext
getSettings()  : array<int, array<string, mixed>>
getThemeContext()  : ThemeContext|null
handleSuggest()  : void
`picker.js` sends the query as a bare `q=…` (no component prefix); Nette gives it to the presenter, not to the signal argument, so `q` is read from the presenter too (as the admin Picker does).
hasServiceByType()  : bool
Returns whether the container has a service of the given type.
initializeAllContexts()  : void
injectDeviceDetector()  : void
onCreate()  : void
render()  : void
setAppContext()  : $this
setComponentParameter()  : void
Sets a component parameter.
setCurrencyContext()  : $this
setFieldMap()  : self
setLanguageContext()  : $this
setLeafOnly()  : self
setLocalizationContext()  : $this
setMinLevel()  : self
setPlaceholderKey()  : self
setSettingContext()  : $this
setThemeContext()  : $this
setup()  : void
setupAppContext()  : void
typedComponent()  : T
Returns a subcomponent with a verified type.
frontPresenter()  : BasePresenter|null
Returns the front presenter the component is attached to (null outside the front end or when detached).
getTranslator()  : ITranslator
setTemplateFile()  : void
setTranslator()  : self
createMultiplierComponent()  : Multiplier<string|int, IComponent>
Creates a multiplier for the component.
createNewComponentInstance()  : IComponent|null
Creates a new component instance without adding it to the presenter; used by the multiplier.
createStandardComponent()  : IComponent|null
Creates a standard component (not a multiplier).
prepareTemplate()  : void
resolveLanguageId()  : int
resolveMapTargets()  : array<string, string>
`htmlId` of sibling controls for `data-picker-map-*`. A missing control (the parameter is not in the category) is left out.
resolvePreferRegionId()  : int|null
The country of the website localization (`cms_system_localizations.cms_system_regions_region_id`) takes precedence in the offer.
resolveRegionLabel()  : string
Label of the stored value (advert edit, filter from URL); a nonexistent id gives empty text.

Constants

SUGGEST_CACHE_SECONDS

The response depends only on `q`, the language and the field configuration, not on the session, so the browser HTTP cache applies. `private`, not `public`: the front end response carries the session `Set-Cookie` and a shared cache (CDN/proxy) would hand it to other visitors.

private int SUGGEST_CACHE_SECONDS = 3600

Properties

$componentParameters

protected array<string, mixed> $componentParameters = []

component parameters set by setComponentParameter()

$translatorDomain

protected string|null $translatorDomain = 'front.system.components.regionSuggest'

$fieldMap

Item data key (`city`, `zip`, `country`) mapped to the name of a sibling form control that `picker.js` prefills after selection (`data-picker-map-*`). Preview only.

private array<string, string> $fieldMap = []

$leafOnly

Only leaves of the municipality type (advert form).

private bool $leafOnly = false

$minLevel

Lowest tree level offered (1 = country too, 2 = from region).

private int $minLevel = 2

$placeholderKey

Translation key of the own field placeholder (relative to the component domain); `null` = by variant (`placeholder` / `filterPlaceholder`). The watchdog also offers region and district, hence its own text.

private string|null $placeholderKey = null

Methods

__call()

Dispatches `renderXyz()` to `render('Xyz', ...$args)`.

public __call(string $name, array<string|int, mixed> $args) : mixed

Called only when the component has no renderXyz() method of its own.

Parameters
$name : string
$args : array<string|int, mixed>

createComponent()

public createComponent(string $name) : IComponent|null
Parameters
$name : string
Return values
IComponent|null

getComponentParameter()

Returns a component parameter, or null when it is not set.

public getComponentParameter(string $name) : mixed
Parameters
$name : string

getContainer()

public getContainer() : Container
Return values
Container

getSettings()

public getSettings() : array<int, array<string, mixed>>
Return values
array<int, array<string, mixed>>

handleSuggest()

`picker.js` sends the query as a bare `q=…` (no component prefix); Nette gives it to the presenter, not to the signal argument, so `q` is read from the presenter too (as the admin Picker does).

public handleSuggest([string $q = '' ]) : void

A GET without side effects, so CSRF is not handled. The Api holds the rate limit (RegionPresenter::internalActionSuggest(), 60/min/IP); over the limit: HTTP 429 and empty items.

Parameters
$q : string = ''

hasServiceByType()

Returns whether the container has a service of the given type.

public hasServiceByType(string $className) : bool

The name is composed dynamically (module plus component), so class_exists() runs first, and a true result guarantees a valid type.

Parameters
$className : string
Tags
phpstan-assert-if-true

class-string $className

Return values
bool

render()

public render(BaseControl $input[, bool $compact = false ][, BaseControl|null $display = null ]) : void
Parameters
$input : BaseControl

value carrier (region_id), a hidden control of the host form

$compact : bool = false

variant for the list filter (Style_Filter.latte of the host)

$display : BaseControl|null = null

text control of the host used as the suggester field (distance filter: unselected text goes into the URL too); null = the component draws its own field

setComponentParameter()

Sets a component parameter.

public setComponentParameter(string $name, mixed $value) : void
Parameters
$name : string
$value : mixed

setFieldMap()

public setFieldMap(array<string, string> $fieldMap) : self
Parameters
$fieldMap : array<string, string>
Return values
self

setLeafOnly()

public setLeafOnly(bool $leafOnly) : self
Parameters
$leafOnly : bool
Return values
self

setMinLevel()

public setMinLevel(int $minLevel) : self
Parameters
$minLevel : int
Return values
self

setPlaceholderKey()

public setPlaceholderKey(string|null $placeholderKey) : self
Parameters
$placeholderKey : string|null
Return values
self

typedComponent()

Returns a subcomponent with a verified type.

public typedComponent(string $name, T> $type) : T

Use it instead of an inline @var above $this['x'] (which does not narrow the type) and instead of the generic IComponent that $this['x'] returns. See Form::typedComponent().

Parameters
$name : string
$type : T>
Tags
template
Return values
T

frontPresenter()

Returns the front presenter the component is attached to (null outside the front end or when detached).

protected frontPresenter() : BasePresenter|null
Return values
BasePresenter|null

getTranslator()

protected getTranslator() : ITranslator
Return values
ITranslator

setTemplateFile()

protected setTemplateFile(string $dir, string $filename) : void
Parameters
$dir : string
$filename : string

setTranslator()

protected setTranslator(ITranslator $translator) : self
Parameters
$translator : ITranslator
Return values
self

createMultiplierComponent()

Creates a multiplier for the component.

private createMultiplierComponent(string $name) : Multiplier<string|int, IComponent>
Parameters
$name : string
Return values
Multiplier<string|int, IComponent>

createNewComponentInstance()

Creates a new component instance without adding it to the presenter; used by the multiplier.

private createNewComponentInstance(string $baseName[, int|string|null $uniqueKey = null ]) : IComponent|null
Parameters
$baseName : string
$uniqueKey : int|string|null = null
Return values
IComponent|null

createStandardComponent()

Creates a standard component (not a multiplier).

private createStandardComponent(string $name) : IComponent|null
Parameters
$name : string
Return values
IComponent|null

prepareTemplate()

private prepareTemplate(BaseControl $input) : void
Parameters
$input : BaseControl

resolveLanguageId()

private resolveLanguageId() : int
Return values
int

resolveMapTargets()

`htmlId` of sibling controls for `data-picker-map-*`. A missing control (the parameter is not in the category) is left out.

private resolveMapTargets(BaseControl $input) : array<string, string>
Parameters
$input : BaseControl
Return values
array<string, string>

resolvePreferRegionId()

The country of the website localization (`cms_system_localizations.cms_system_regions_region_id`) takes precedence in the offer.

private resolvePreferRegionId() : int|null
Return values
int|null

resolveRegionLabel()

Label of the stored value (advert edit, filter from URL); a nonexistent id gives empty text.

private resolveRegionLabel(int $regionId) : string
Parameters
$regionId : int
Return values
string
On this page

Search results