CoolCMS API

Rating extends BaseComponent

in package

• Application

uses InitializationTrait, HandleTrait, FormTrait

Generic rating component for any rateable content (articles, profiles, adverts...).

Table of Contents

Constants

REVIEWS_PER_PAGE  : mixed = 1

SORT_BEST  : mixed = 'best'

SORT_HELPFUL  : mixed = 'helpful'

SORT_NEWEST  : mixed = 'newest'

SORT_WORST  : mixed = 'worst'

SORTS  : mixed = [self::SORT_NEWEST => ['id' => false], self::SO...

Allowed `$sort` values mapped to the manager `orderBy`; an unknown value falls back to `newest`.

STYLE_CLASSIC  : mixed = 'Classic'

STYLE_NUMBER  : mixed = 'Number'

STYLE_REVIEW  : mixed = 'Review'

STYLE_REVIEWS  : mixed = 'Reviews'

STYLE_REVIEWS_DETAILED  : mixed = 'ReviewsDetailed'

Detailed review list (summary, star filter, sorting).

STYLE_STATIC  : mixed = 'Static'

STYLE_SUMMARY  : mixed = 'Summary'

STYLE_THUMBS  : mixed = 'Thumbs'

MODAL_REPLY_TARGET  : mixed = 'ratingReply'

MODAL_TARGET  : mixed = 'ratingReview'

PROS_CONS_MAX_ITEMS  : mixed = 10

Max count and length of pros/cons items (server-side sanitization).

PROS_CONS_MAX_LENGTH  : mixed = 120

Properties

$container  : Container

$page  : int

$routerDispatcher  : RouterDispatcher

$sort  : string

Review list sorting, see {@see self::SORTS}.

$stars  : int

Star-count filter of the review list; 0 means no filter (default, other styles ignore it).

$style  : string

$threadId  : int

$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

$allowAnonymous  : bool

$allowVoting  : bool

$boundThreadId  : int

IMPORTANT: thread set by the parent on the server, see `setThreadId()`. `$threadId` is `#[Persistent]` (comes from the URL), so taking it from a hidden field would let a form on a foreign page write a rating into any thread, e.g. the visitor's own profile or a thread with ratings disabled. Writes (stars and reviews) are therefore allowed only into this thread; a component without a server-set thread never writes.

$eventDispatcher  : EventDispatcher

$hasVoted  : bool|null

$modalRegistry  : ModalRegistry

$overrideRatingUseAutoApprovalReview  : bool|null

$overrideRatingUseAutoApprovalStars  : bool|null

null uses the DB setting; true/false overrides it for this instance.

$ownerId  : int

$perPage  : int|null

Reviews per page; `null` means {@see REVIEWS_PER_PAGE}.

$ratingManager  : RatingManager

$ratingThreadManager  : RatingThreadManager

$showSummary  : bool

Whether to render the summary inside `STYLE_REVIEWS_DETAILED`, see `setShowSummary()`.

$thumbs  : array<int, string>

Thumbs shown by `STYLE_THUMBS`: 'up' (value 5) and/or 'down' (value 1).

$userManager  : UserManager

$verifiedBuyersResolver  : null|callable(array<int, int>): array<int, int>

Optional resolver telling which of the given authors really bought the item.

Methods

__call()  : mixed

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

__construct()  : mixed

canRespond()  : bool

Whether the current visitor may reply to reviews (logged-in content owner).

canVote()  : bool

Whether the current visitor may rate (voting enabled and logged in, or anonymous allowed).

createComponent()  : IComponent|null

createComponentReplyForm()  : Form

Review reply form (in a modal): textarea and submit.

createComponentReviewForm()  : Form

Written review form (in a modal): stars, text, pros and cons.

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

getPerPage()  : int

Effective reviews per page: the instance setting, otherwise the constant.

getRouterDispatcher()  : RouterDispatcher

getSettingContext()  : SettingContext

getSettings()  : array<int, array<string, mixed>>

getThemeContext()  : ThemeContext|null

handleFilterStars()  : void

AJAX signal: filters the list by star count (0 clears the filter).

handlePage()  : void

AJAX signal: switches the review list page.

handleRate()  : void

AJAX signal: saves the star rating (1-5) and redraws the component.

handleReportReview()  : void

AJAX signal: reports an inappropriate review.

handleShowReplyForm()  : void

Signal that shows the reply form in a modal (`STYLE_REVIEW`).

handleShowReviewForm()  : void

Signal that shows the review form in a modal (`STYLE_REVIEW`).

handleSortReviews()  : void

AJAX signal: sorts the review list. An unknown value falls back to "newest" (checked by `resolveSort()` on render), so a hand-edited URL breaks nothing.

handleVoteReview()  : void

AJAX signal: vote on the helpfulness of one review (thumb up/down).

hasServiceByType()  : bool

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

initializeAllContexts()  : void

initializeRender()  : void

Public wrapper called by `FormTrait::handleSubmitSuccess()` before `redrawControl('rating')`.

injectDeviceDetector()  : void

loadState()  : void

Ignores the persistent `threadId` from the URL when the parent set the thread.

onCreate()  : void

onReviewError()  : void

Re-renders the modal with errors when validation fails (no stars, forged value).

onSubmit()  : void

Handles the review submission.

onSubmitReply()  : void

Handles the review reply submission.

render()  : void

Default render; takes the style as the first parameter and the other `renderX()` call it.

renderNumber()  : void

renderReview()  : void

renderReviews()  : void

renderReviewsDetailed()  : void

Detailed review list: summary bars, star filter and sorting.

renderStatic()  : void

renderSummary()  : void

renderThumbs()  : void

Like/dislike rating with two thumbs. Under the hood it is the same star rating: thumb up is value 5, thumb down is value 1. Counts come from the denormalized `count_5` / `count_1` on the thread.

setAllowAnonymous()  : self

setAllowVoting()  : self

setAppContext()  : $this

setComponentParameter()  : void

Sets a component parameter.

setCurrencyContext()  : $this

setLanguageContext()  : $this

setLocalizationContext()  : $this

setOverrideRatingUseAutoApprovalReview()  : self

Overrides the DB flag `rating.useAutoApprovalReviews` for this instance; null uses the DB setting (default).

setOverrideRatingUseAutoApprovalStars()  : self

Overrides the DB flag `autoApprovalStars` for this instance; null uses the DB setting (default).

setOwnerId()  : self

setPerPage()  : self

Reviews per page for this instance (at least 1).

setSettingContext()  : $this

setShowSummary()  : self

Sets whether `STYLE_REVIEWS_DETAILED` also renders the summary (big score, bars, statistics).

setStyle()  : self

setThemeContext()  : $this

setThreadId()  : self

setThumbs()  : self

Limits the thumbs rendered by `STYLE_THUMBS`, e.g. ['up'] for like only.

setup()  : void

setupAppContext()  : void

setVerifiedBuyersResolver()  : self

Sets how to find which review authors really bought the rated item ("verified purchase").

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).

getModalTarget()  : string

getReplyModalTarget()  : string

getTranslator()  : ITranslator

setTemplateFile()  : void

setTranslator()  : self

buildRating()  : Rating

Builds the rating entity shared by stars and reviews.

buildSaveMeta()  : array<string, bool>

Builds the meta array for `save()`, passing component-level overrides to the Api layer.

computeCounts()  : array<int, int>

Returns the array [1..5 => count] from the given rating list.

createModalContent()  : string

createModalEvent()  : ModalWindowEvent

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.

createReplyModalContent()  : string

createReplyModalEvent()  : ModalWindowEvent

createStandardComponent()  : IComponent|null

Creates a standard component (not a multiplier).

createSuccessContent()  : string

decodeItems()  : array<int, string>|null

Decodes and sanitizes a JSON array of strings from a hidden input (pros/cons).

handleSubmitError()  : void

Handles a submission error. `$resultKey` selects the translation key under `.result.*` (`duplicated` for the dedup rejection from {@see \App\UI\Api\Base\Models\Managers\RatingManager::beforeSave()}, otherwise the generic `failure`), so the user sees "already rated" instead of a generic error.

handleSubmitSuccess()  : void

Handles a successful submission.

initializeAggregate()  : void

Loads the denormalized aggregate (average and count) from the thread.

initializeForStyle()  : void

Loads template data according to the render style.

initializeMyVotes()  : void

Loads how this visitor voted on the displayed reviews, to highlight their choice and not offer it again.

initializeReviewFull()  : void

Loads aggregate, reviews and star distribution for `STYLE_REVIEW`.

initializeReviews()  : void

Loads approved ratings of the thread, paginated, plus their authors' avatars.

initializeReviewsDetailed()  : void

Summary plus review list with filter and sorting (`STYLE_REVIEWS_DETAILED`).

initializeSummary()  : void

Loads aggregate and star distribution for `STYLE_SUMMARY` (without the full review list).

initializeThumbs()  : void

Reads like/dislike counts from the denormalized thread columns (`count_5` is like, `count_1` is dislike), without querying the rating list, so it is fine in listings.

initializeUsers()  : void

Loads avatars of the users who rated.

normalizeText()  : string|null

Returns null for empty text (stars only), otherwise the trimmed text.

refusedVoteResultKey()  : string

Returns the translation key for a rejection from `canVote()`. A logged-in user who already rated gets the "already rated" message (same as the Api dedup), others a generic error.

resolveSort()  : string

Validated `$sort` value; an unknown one (e.g. from a hand-edited URL) falls back to `newest`.

resolveSubmittedThreadId()  : int

Returns the thread for writing a review. A component with a server-set thread (`setThreadId()` in the parent) always uses that one; any other hidden-field value yields 0, so `canVote()` rejects the write. Without a set thread nothing is written.

updateModalContent()  : void

Aktualizuje obsah modalu

userHasVoted()  : bool

Checks whether the given user already has a review in this thread (even a pending one).