CoolCMS API

Form extends BootstrapForm
in package

Application

Application form: extension methods registered in {@see registerExtensionMethods()} and the reCAPTCHA one from {@see \App\Core\Forms\ReCaptcha\RuntimeReCaptchaBinding} (`Container::extensionMethod`).

PHPStan does not see them through __call, and a Container stub collides with the phpstan-nette stub (double class declaration), so the @method tags live on this form, where all calls go.

Constants

ADMIN_CSRF_MESSAGE : string = '//admin.system.form.csrf.expired': Message of the admin CSRF protection (`addProtection()`); global key in `admin.system.form.csrf`.
EDITOR_MODE_FULL : mixed = 'full': `data-editor` value: full TinyMCE (admin content of pages, articles, e-mails, PDF templates).
EDITOR_MODE_RAW : mixed = 'raw': `data-editor` value: TinyMCE that drops nothing (page sections).
EDITOR_MODE_SIMPLE : mixed = 'simple': `data-editor` value: reduced TinyMCE (advert parameters, front end forms).
INTEGER_MESSAGE : string = '//admin.general.integer.invalid': Message for an integer field that receives anything else; global key (`admin.general` in NEON).
INTEGER_MIN_MESSAGE : string = '//admin.general.integer.min': Message for a lower limit without an upper one; Nette fills `%d` from the rule argument.
INTEGER_RANGE_MESSAGE : string = '//admin.general.integer.range': Message for a `from-to` range; Nette fills `%d` from the rule argument (the real limit).
VAT_RATE_MESSAGE : string = '//admin.general.vatRate.invalid': Message for a VAT rate outside 0-100 or non-numeric; global key (`admin.general.vatRate` in NEON).

Properties

$onSuccess : array<string|int, callable(static, never): void>: Retyped without changing value or behavior: `Nette\Forms\Form::invokeHandlers()` reads the declared parameter types of a handler by reflection and passes values in that shape (array, ArrayHash, DTO). A handler `(Form $form, ArrayHash $values)` is therefore correct; the phpstan-nette stub (`callable(static, mixed)`) would reject it, while `never` accepts any type.
$onValidate : array<string|int, callable(static, never): void>: Same for `Container::validate()`: the handler receives values in the type it declares.
$translatorDomain : string
$extensionMethodsRegistered : bool

Methods

__construct() : mixed
addBoundedInteger() : TextInput: Adds an integer field with a server-enforced limit (module settings: per-page counts, days, hours).
addCheckbox() : Checkbox
addCheckboxList() : HtmlCaptionCheckboxListInput: Adds a checkbox list that keeps Html in option captions.
addDependentSelectBox() : DependentSelectBox
addEditor() : TextArea: Adds a textarea that client JS (`rich-editor.js`) replaces with the full TinyMCE editor (headings, fonts, links, images, tables, source code).
addEditorControls() : TextArea: Same as {@see addEditor()} but adds the field to any container, including a row of {@see \Contributte\FormMultiplier\Multiplier}. The multiplier factory gives only a plain `Container`, on which the instance `addEditor()` cannot be called, so the logic is static and both paths share it.
addImageUpload() : UploadControl: Adds a single image upload field (main photo): a classic `<input type=file>` with an instant client preview (admin JS `image-upload.js`). It is rendered by the reusable component {@see \App\UI\Admin\Base\Components\ImageUploadComponent\ImageUpload} (`{control imageUpload $form, '<name>', $currentUrl}`), which also renders the helper fields.
addImageUploadControls() : UploadControl: Same as {@see addImageUpload()} but adds the field to any container, including a {@see \Contributte\FormMultiplier\Multiplier} row (gallery). The multiplier factory gives only a plain `Container`, on which the instance `addImageUpload()` cannot be called, so the logic is static and both paths share it.
addInvisibleReCaptcha() : BaseControl
addRawEditor() : TextArea: Adds a textarea with a TinyMCE editor that drops nothing (`data-editor="raw"`): the same toolbar as {@see addEditor()} (including the "Components" button and source code), but without the schema and `extended_valid_elements` with which `full` silently strips `<button>`, `<svg>`, `<form>`, custom elements and unknown attributes.
addRawEditorControls() : TextArea: Same as {@see addRawEditor()} but adds the field to any container, including a {@see \Contributte\FormMultiplier\Multiplier} row; see {@see addEditorControls()}.
addSimpleEditor() : TextArea: Adds a textarea with the reduced TinyMCE editor (`data-editor="simple"`): bold/italic/underline, colors, alignment, lists and a table. No links, images, media or source code, even when pasted (`valid_elements` in the JS configuration).
addSimpleEditorControls() : TextArea: Same as {@see addSimpleEditor()} but for any container (a {@see \Contributte\FormMultiplier\Multiplier} row); see {@see addEditorControls()}.
addVatRate() : TextInput: Adds a VAT rate field in percent, 0-100, decimals allowed (5.5 / 13.5), comma or dot.
getTranslateFnc() : callable: Returns the function that form traits use to build field message keys (`$t('field.required')`).
getTranslatorDomain() : string
httpDataValue() : mixed: Returns the raw submitted value under `$key` (typically a whole multiplier array for limits in `onAnchor`), or null outside an array (`getHttpData()` returns `array|FileUpload|string|null`).
registerExtensionMethods() : void: Registers the extra field methods as extension methods on `Container`, so `addEditor()` / `addImageUpload()` also work on a plain `Container`, typically a {@see \Contributte\FormMultiplier\Multiplier} row, which builds a base `Container` instead of a `Form`. Without the registration it fails with "Call to undefined method Container::addEditor()".
setTranslatorDomain() : self: Sets the translator domain; null means no prefix, same as an empty string.
typedComponent() : T: Returns a form component with a verified type, instead of an inline `@var` above `$form['x']` (which does not narrow the type) or the generic `IComponent` that `$form['x']` returns.
useDomainTranslator() : self: Sets a translator wrapped in `PrefixedTranslator` for the domain.
validateImageOrVector() : bool: Accepts a raster image (rule {@see Form::IMAGE}) or SVG.

ADMIN_CSRF_MESSAGE

Message of the admin CSRF protection (`addProtection()`); global key in `admin.system.form.csrf`.


    public
        string
    ADMIN_CSRF_MESSAGE
    = '//admin.system.form.csrf.expired'

Without it Nette shows its English default ("Your session has expired. Please return to the home page and try again.") in a Czech admin. Only for forms with the Contributte translator (it resolves the // prefix); a form without a translator passes the translated text. Front end forms do not use it: the admin key is not loaded there and a missing key crashes the page.

EDITOR_MODE_FULL

`data-editor` value: full TinyMCE (admin content of pages, articles, e-mails, PDF templates).


    public
        mixed
    EDITOR_MODE_FULL
    = 'full'

EDITOR_MODE_RAW

`data-editor` value: TinyMCE that drops nothing (page sections).


    public
        mixed
    EDITOR_MODE_RAW
    = 'raw'

EDITOR_MODE_SIMPLE

`data-editor` value: reduced TinyMCE (advert parameters, front end forms).


    public
        mixed
    EDITOR_MODE_SIMPLE
    = 'simple'

INTEGER_MESSAGE

Message for an integer field that receives anything else; global key (`admin.general` in NEON).


    public
        string
    INTEGER_MESSAGE
    = '//admin.general.integer.invalid'

INTEGER_MIN_MESSAGE

Message for a lower limit without an upper one; Nette fills `%d` from the rule argument.


    public
        string
    INTEGER_MIN_MESSAGE
    = '//admin.general.integer.min'

INTEGER_RANGE_MESSAGE

Message for a `from-to` range; Nette fills `%d` from the rule argument (the real limit).


    public
        string
    INTEGER_RANGE_MESSAGE
    = '//admin.general.integer.range'

VAT_RATE_MESSAGE

Message for a VAT rate outside 0-100 or non-numeric; global key (`admin.general.vatRate` in NEON).


    public
        string
    VAT_RATE_MESSAGE
    = '//admin.general.vatRate.invalid'

$onSuccess

Retyped without changing value or behavior: `Nette\Forms\Form::invokeHandlers()` reads the declared parameter types of a handler by reflection and passes values in that shape (array, ArrayHash, DTO). A handler `(Form $form, ArrayHash $values)` is therefore correct; the phpstan-nette stub (`callable(static, mixed)`) would reject it, while `never` accepts any type.


        public
            array<string|int, callable(static, never): void>
    $onSuccess
     = []

$onValidate

Same for `Container::validate()`: the handler receives values in the type it declares.


        public
            array<string|int, callable(static, never): void>
    $onValidate
     = []

$translatorDomain


        protected
            string
    $translatorDomain
     = ''

$extensionMethodsRegistered


        private
        static    bool
    $extensionMethodsRegistered
     = false

__construct()


    public
                    __construct([IContainer|null $parent = null ]) : mixed

Parameters

$parent : IContainer|null = null

addBoundedInteger()

Adds an integer field with a server-enforced limit (module settings: per-page counts, days, hours).


    public
                    addBoundedInteger(string $name, Html|string|null $label, int $min[, int|null $max = null ]) : TextInput

An empty value passes (the field is nullable and rules are skipped on an empty field); the caller adds setRequired(). The limit is also written to min/max of <input type=number>, but the server decides because an HTML attribute can be bypassed. Without $max only the lower limit is enforced. Messages are global (//admin.general.integer.*), so they need not be written per field.

Parameters

$name : string
$label : Html|string|null
$min : int
$max : int|null = null

Return values

TextInput

addCheckbox()


    public
                    addCheckbox(string $name[, mixed $caption = null ]) : Checkbox

Parameters

$name : string
$caption : mixed = null

Return values

Checkbox

addCheckboxList()

Adds a checkbox list that keeps Html in option captions.


    public
                    addCheckboxList(string $name[, mixed $label = null ][, array<int|string, string|Stringable|HtmlStringable>|null $items = null ]) : HtmlCaptionCheckboxListInput

The Bootstrap layer otherwise casts a caption to string and the tags are printed to the user, see HtmlCaptionCheckboxListInput. Needed for filter option counts ("Sony (3)"), where an option with zero gets its own class. Captions may also be Stringable (typically NotTranslate with a DB value): the Bootstrap layer casts them to string, Html captions are kept by this class.

Parameters

$name : string
$label : mixed = null
$items : array<int|string, string|Stringable|HtmlStringable>|null = null

Return values

HtmlCaptionCheckboxListInput

addDependentSelectBox()


    public
                    addDependentSelectBox(string $name, string|object|null $label, array<string|int, string> $parents, callable(array<string, mixed>): DependentData $callback) : DependentSelectBox

Parameters

$name : string
$label : string|object|null
$parents : array<string|int, string>
$callback : callable(array<string, mixed>): DependentData

Return values

DependentSelectBox

addEditor()

Adds a textarea that client JS (`rich-editor.js`) replaces with the full TinyMCE editor (headings, fonts, links, images, tables, source code).


    public
                    addEditor(string $name[, string|Html|null $caption = null ]) : TextArea

Activated by the data-editor="full" attribute, so Latte only renders {input field}. IMPORTANT: the content is not sanitized on the server; the field is for admin editors (trusted authors). For user input (front end, advert parameters) use addSimpleEditor(), whose whitelist is guarded by EditorHtmlSanitizer.

Optional attributes on the returned field:

->setHtmlAttribute('data-editor-height', 320): fixed height in px (otherwise auto height),
->setHtmlAttribute('data-relative-url', 0): disables conversion to relative URLs (absolute links, typically an e-mail body).

Parameters

$name : string
$caption : string|Html|null = null

Return values

TextArea

addEditorControls()

Same as {@see addEditor()} but adds the field to any container, including a row of {@see \Contributte\FormMultiplier\Multiplier}. The multiplier factory gives only a plain `Container`, on which the instance `addEditor()` cannot be called, so the logic is static and both paths share it.


    public
            static        addEditorControls(Container $container, string $name[, string|Html|null $caption = null ]) : TextArea

Parameters

$container : Container
$name : string
$caption : string|Html|null = null

Return values

TextArea

addImageUpload()

Adds a single image upload field (main photo): a classic `<input type=file>` with an instant client preview (admin JS `image-upload.js`). It is rendered by the reusable component {@see \App\UI\Admin\Base\Components\ImageUploadComponent\ImageUpload} (`{control imageUpload $form, '<name>', $currentUrl}`), which also renders the helper fields.


    public
                    addImageUpload(string $name[, string|Html|null $caption = null ][, int $maxFileSizeMb = 10 ][, bool $allowDelete = true ][, bool $allowVector = false ]) : UploadControl

Besides the upload it adds satellite fields:

<name>CurrentId (hidden): id of the existing Asset when editing, to tell keep / replace / delete apart,
<name>Delete (checkbox, hidden in the UI): flag to delete the current image, set by JS on "Remove"; added only when $allowDelete = true.

$allowDelete = false omits the flag and the "Remove" button (the component hides it), suitable in a Multiplier row where removing the whole row does the job.

Writing the uploaded file (variants plus the Asset entity) is done by the API layer; the admin form only passes the bytes (base64) in the save payload.

Parameters

$name : string
$caption : string|Html|null = null
$maxFileSizeMb : int = 10
$allowDelete : bool = true
$allowVector : bool = false

Return values

UploadControl

addImageUploadControls()

Same as {@see addImageUpload()} but adds the field to any container, including a {@see \Contributte\FormMultiplier\Multiplier} row (gallery). The multiplier factory gives only a plain `Container`, on which the instance `addImageUpload()` cannot be called, so the logic is static and both paths share it.


    public
            static        addImageUploadControls(Container $container, string $name[, string|Html|null $caption = null ][, int $maxFileSizeMb = 10 ][, bool $allowDelete = true ][, bool $allowVector = false ]) : UploadControl

Parameters

$container : Container
$name : string
$caption : string|Html|null = null
$maxFileSizeMb : int = 10
$allowDelete : bool = true
$allowVector : bool = false

Return values

UploadControl

addInvisibleReCaptcha()


    public
                    addInvisibleReCaptcha([string $name =  = '\'recaptcha\'' ][, bool $required =  = 'true' ][, string|null $message =  = 'null' ]) : BaseControl

Parameters

$name : string = = '\'recaptcha\''
$required : bool = = 'true'
$message : string|null = = 'null'

Return values

BaseControl

addRawEditor()

Adds a textarea with a TinyMCE editor that drops nothing (`data-editor="raw"`): the same toolbar as {@see addEditor()} (including the "Components" button and source code), but without the schema and `extended_valid_elements` with which `full` silently strips `<button>`, `<svg>`, `<form>`, custom elements and unknown attributes.


    public
                    addRawEditor(string $name[, string|Html|null $caption = null ]) : TextArea

Page sections carry Bootstrap markup and ui-demo elements and must render 1:1 on the front end; the full whitelist would break them on save.

IMPORTANT: as with full, the content is not sanitized on the server and reaches the front end through |noescape. Use it only in admin forms behind RBAC, never on the front end or anywhere a visitor writes, otherwise it is a stored XSS. For user input use addSimpleEditor() (whitelist plus EditorHtmlSanitizer).

Parameters

$name : string
$caption : string|Html|null = null

Return values

TextArea

addRawEditorControls()

Same as {@see addRawEditor()} but adds the field to any container, including a {@see \Contributte\FormMultiplier\Multiplier} row; see {@see addEditorControls()}.


    public
            static        addRawEditorControls(Container $container, string $name[, string|Html|null $caption = null ]) : TextArea

Parameters

$container : Container
$name : string
$caption : string|Html|null = null

Return values

TextArea

addSimpleEditor()

Adds a textarea with the reduced TinyMCE editor (`data-editor="simple"`): bold/italic/underline, colors, alignment, lists and a table. No links, images, media or source code, even when pasted (`valid_elements` in the JS configuration).


    public
                    addSimpleEditor(string $name[, string|Html|null $caption = null ]) : TextArea

Use it wherever a user writes the content (front end forms, advert parameters). IMPORTANT: the whitelist must stay in sync with the server sanitizer EditorHtmlSanitizer::ALLOWED_HTML, because a JS-only restriction can be bypassed.

Parameters

$name : string
$caption : string|Html|null = null

Return values

TextArea

addSimpleEditorControls()

Same as {@see addSimpleEditor()} but for any container (a {@see \Contributte\FormMultiplier\Multiplier} row); see {@see addEditorControls()}.


    public
            static        addSimpleEditorControls(Container $container, string $name[, string|Html|null $caption = null ]) : TextArea

Parameters

$container : Container
$name : string
$caption : string|Html|null = null

Return values

TextArea

addVatRate()

Adds a VAT rate field in percent, 0-100, decimals allowed (5.5 / 13.5), comma or dot.


    public
                    addVatRate(string $name[, Html|string|null $label = null ]) : TextInput

A text field, not type=number: a browser with the Czech locale and step validates that its own way. An empty value passes (nullable); the caller adds the required rule. Range and shape are enforced on the server (VatRate::normalize()); the DB gets VatRate::normalize($value) (decimal(5,2)).

Parameters

$name : string
$label : Html|string|null = null

Return values

TextInput

getTranslateFnc()

Returns the function that form traits use to build field message keys (`$t('field.required')`).


    public
                    getTranslateFnc() : callable

The behavior follows the type of the set translator:

prefixed translator (useDomainTranslator, admin createForm): the translator adds the domain itself, so the key must stay relative; otherwise the domain is doubled (PrefixedTranslator prefixes an absolute key again) and the message renders as a raw key;
raw translator (setTranslator plus setTranslatorDomain, front end / admin Login): it does not add the domain, so the key must be absolute (domain.key).

Return values

callable

getTranslatorDomain()


    public
                    getTranslatorDomain() : string

Return values

string

httpDataValue()

Returns the raw submitted value under `$key` (typically a whole multiplier array for limits in `onAnchor`), or null outside an array (`getHttpData()` returns `array|FileUpload|string|null`).


    public
                    httpDataValue(string $key) : mixed

The value is not validated; the caller checks it (see MultiplierLimits).

Parameters

$key : string

registerExtensionMethods()

Registers the extra field methods as extension methods on `Container`, so `addEditor()` / `addImageUpload()` also work on a plain `Container`, typically a {@see \Contributte\FormMultiplier\Multiplier} row, which builds a base `Container` instead of a `Form`. Without the registration it fails with "Call to undefined method Container::addEditor()".


    public
            static        registerExtensionMethods() : void

Called at boot from FormExtension (initialize()) so the registration survives across requests. The instance methods on Form stay (they carry return types for IDE/PHPStan); extension methods apply only where the class has no such method.

setTranslatorDomain()

Sets the translator domain; null means no prefix, same as an empty string.


    public
                    setTranslatorDomain(string|null $domain) : self

Parameters

$domain : string|null

Return values

self

typedComponent()

Returns a form component with a verified type, instead of an inline `@var` above `$form['x']` (which does not narrow the type) or the generic `IComponent` that `$form['x']` returns.


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

Parameters

$name : string
$type : T>

Return values

useDomainTranslator()

Sets a translator wrapped in `PrefixedTranslator` for the domain.


    public
                    useDomainTranslator(Translator $translator, string $domain) : self

Replaces setTranslator() plus setTranslatorDomain(); field labels then need no $t() prefix. It takes the interface (components get Nette\Localization\Translator injected), but only the Contributte translator can prefix, and it always runs in the application; any other is a wiring error.

Parameters

$translator : Translator
$domain : string

Return values

self

validateImageOrVector()

Accepts a raster image (rule {@see Form::IMAGE}) or SVG.


    public
            static        validateImageOrVector(UploadControl $control) : bool

SVG is recognized by extension plus MIME: finfo alone returns image/svg+xml or generic text/xml depending on the libmagic version, so it cannot be relied on. The real security check is sanitization on save (SvgSanitizer); this rule only gives the user a clear form error.

Parameters

$control : UploadControl

Return values

bool

Form extends BootstrapForm in package Application

Table of Contents

Constants

Properties

Methods

Constants

ADMIN_CSRF_MESSAGE

EDITOR_MODE_FULL

EDITOR_MODE_RAW

EDITOR_MODE_SIMPLE

INTEGER_MESSAGE

INTEGER_MIN_MESSAGE

INTEGER_RANGE_MESSAGE

VAT_RATE_MESSAGE

Properties

$onSuccess

$onValidate

$translatorDomain

$extensionMethodsRegistered

Methods

__construct()

Parameters

addBoundedInteger()

Parameters

Return values

addCheckbox()

Parameters

Return values

addCheckboxList()

Parameters

Return values

addDependentSelectBox()

Parameters

Return values

addEditor()

Parameters

Return values

addEditorControls()

Parameters

Return values

addImageUpload()

Parameters

Return values

addImageUploadControls()

Parameters

Return values

addInvisibleReCaptcha()

Parameters

Return values

addRawEditor()

Parameters

Return values

addRawEditorControls()

Parameters

Return values

addSimpleEditor()

Parameters

Return values

addSimpleEditorControls()

Parameters

Return values

addVatRate()

Parameters

Return values

getTranslateFnc()

Return values

getTranslatorDomain()

Return values

httpDataValue()

Parameters

registerExtensionMethods()

setTranslatorDomain()

Parameters

Return values

typedComponent()

Parameters

Tags

Return values

useDomainTranslator()

Parameters

Form extends BootstrapForm
in package

Application