0

Final Class Yiisoft\Yii\DataView\Pagination\KeysetPagination

InheritanceYiisoft\Yii\DataView\Pagination\KeysetPagination » Yiisoft\Widget\Widget
ImplementsYiisoft\Yii\DataView\Pagination\PaginationWidgetInterface
Uses TraitsYiisoft\Yii\DataView\Pagination\PaginationContextTrait

Widget for rendering {@see KeysetPaginator}.

Public Methods

Hide inherited methods

Method Description Defined By
addLinkClass() Adds one or more CSS classes to the existing classes of the "previous"/"next" control. Yiisoft\Yii\DataView\Pagination\KeysetPagination
ariaLabelNav() Sets the aria-label of the nav container. Pass null to omit it. Yiisoft\Yii\DataView\Pagination\KeysetPagination
ariaLabelNext() Sets the aria-label of the "next page" link. Pass null to omit it. Yiisoft\Yii\DataView\Pagination\KeysetPagination
ariaLabelPrevious() Sets the aria-label of the "previous page" link. Pass null to omit it. Yiisoft\Yii\DataView\Pagination\KeysetPagination
containerAttributes() Sets the container element attributes. Yiisoft\Yii\DataView\Pagination\KeysetPagination
containerTag() Sets the container tag name. Yiisoft\Yii\DataView\Pagination\KeysetPagination
context() Creates a new instance with the specified pagination context. Yiisoft\Yii\DataView\Pagination\PaginationContextTrait
create() Creates a new instance with the specified paginator and context. Yiisoft\Yii\DataView\Pagination\KeysetPagination
disabledItemClass() Sets the CSS class for disabled item elements. Yiisoft\Yii\DataView\Pagination\KeysetPagination
disabledLinkAttributes() Sets HTML attributes for a disabled "previous"/"next" control, layered on top of {@see linkAttributes()}. Yiisoft\Yii\DataView\Pagination\KeysetPagination
disabledLinkClass() Sets the CSS class for a disabled "previous"/"next" control. Yiisoft\Yii\DataView\Pagination\KeysetPagination
itemAttributes() Sets the item element attributes. Yiisoft\Yii\DataView\Pagination\KeysetPagination
itemTag() Sets the item tag name that wraps the "previous"/"next" control. Yiisoft\Yii\DataView\Pagination\KeysetPagination
labelNext() Sets the label for the next page link. Yiisoft\Yii\DataView\Pagination\KeysetPagination
labelPrevious() Sets the label for the previous page link. Yiisoft\Yii\DataView\Pagination\KeysetPagination
linkAttributes() Sets the link attributes. Yiisoft\Yii\DataView\Pagination\KeysetPagination
linkClass() Set new link classes. Yiisoft\Yii\DataView\Pagination\KeysetPagination
listAttributes() Sets the list element attributes. Yiisoft\Yii\DataView\Pagination\KeysetPagination
listTag() Sets the list tag name. Yiisoft\Yii\DataView\Pagination\KeysetPagination
paginator() Creates a new instance with the specified paginator. Yiisoft\Yii\DataView\Pagination\KeysetPagination
render() Renders the pagination controls. Yiisoft\Yii\DataView\Pagination\KeysetPagination
showOnSinglePage() Yiisoft\Yii\DataView\Pagination\KeysetPagination

Protected Methods

Hide inherited methods

Method Description Defined By
getContext() Gets the current pagination context. Yiisoft\Yii\DataView\Pagination\PaginationContextTrait

Method Details

Hide inherited methods

addLinkClass() public method

Adds one or more CSS classes to the existing classes of the "previous"/"next" control.

Multiple classes can be added by passing them as separate arguments. null values are filtered out automatically.

public self addLinkClass ( \BackedEnum|string|null $class )
$class \BackedEnum|string|null

One or more CSS class names to add. Pass null to skip adding a class.

return self

A new instance with the specified CSS classes added to existing ones.

                public function addLinkClass(BackedEnum|string|null ...$class): self
{
    $new = clone $this;
    Html::addCssClass($new->linkAttributes, $class);
    return $new;
}

            
ariaLabelNav() public method

Sets the aria-label of the nav container. Pass null to omit it.

The value is applied only when accessibility is enabled and only when aria-label is not already present in {@see \Yiisoft\Yii\DataView\Pagination\containerAttributes()}. When rendered via GridView/ListView, it is translated.

public self ariaLabelNav ( string|null $label )
$label string|null

The aria-label for the nav container.

return self

New instance with the specified nav aria-label.

                public function ariaLabelNav(?string $label): self
{
    $new = clone $this;
    $new->ariaLabelNav = $label;
    return $new;
}

            
ariaLabelNext() public method

Sets the aria-label of the "next page" link. Pass null to omit it.

The value is applied only when accessibility is enabled and only when aria-label is not already present in {@see \Yiisoft\Yii\DataView\Pagination\linkAttributes()}. When rendered via GridView/ListView, it is translated.

public self ariaLabelNext ( string|null $label )
$label string|null

The aria-label for the "next page" link.

return self

New instance with the specified next link aria-label.

                public function ariaLabelNext(?string $label): self
{
    $new = clone $this;
    $new->ariaLabelNext = $label;
    return $new;
}

            
ariaLabelPrevious() public method

Sets the aria-label of the "previous page" link. Pass null to omit it.

The value is applied only when accessibility is enabled and only when aria-label is not already present in {@see \Yiisoft\Yii\DataView\Pagination\linkAttributes()}. When rendered via GridView/ListView, it is translated.

public self ariaLabelPrevious ( string|null $label )
$label string|null

The aria-label for the "previous page" link.

return self

New instance with the specified previous link aria-label.

                public function ariaLabelPrevious(?string $label): self
{
    $new = clone $this;
    $new->ariaLabelPrevious = $label;
    return $new;
}

            
containerAttributes() public method

Sets the container element attributes.

public self containerAttributes ( array $attributes )
$attributes array

HTML attributes for the container element.

return self

New instance with the specified container attributes.

                public function containerAttributes(array $attributes): self
{
    $new = clone $this;
    $new->containerAttributes = $attributes;
    return $new;
}

            
containerTag() public method

Sets the container tag name.

public self containerTag ( string|null $tag )
$tag string|null

The tag name for the container element. Common values: 'nav', 'div'. Use null to omit the container.

return self

New instance with the specified container tag.

throws InvalidArgumentException

If tag name is empty.

                public function containerTag(?string $tag): self
{
    if ($tag === '') {
        throw new InvalidArgumentException('Tag name cannot be empty.');
    }
    $new = clone $this;
    $new->containerTag = $tag;
    return $new;
}

            
context() public method

Defined in: Yiisoft\Yii\DataView\Pagination\PaginationContextTrait::context()

Creates a new instance with the specified pagination context.

public static context ( Yiisoft\Yii\DataView\Pagination\PaginationContext $context )
$context Yiisoft\Yii\DataView\Pagination\PaginationContext

The pagination context to use.

return Yiisoft\Yii\DataView\Pagination\KeysetPagination

New instance with the specified context.

                final public function context(PaginationContext $context): static
{
    $new = clone $this;
    $new->context = $context;
    return $new;
}

            
create() public static method

Creates a new instance with the specified paginator and context.

public static self create ( \Yiisoft\Data\Paginator\KeysetPaginator $paginator, string $nextUrlPattern, string $previousUrlPattern, boolean $accessibility = false, \Yiisoft\Translator\TranslatorInterface|null $translator = null, string $translationCategory = BaseListView::DEFAULT_TRANSLATION_CATEGORY )
$paginator \Yiisoft\Data\Paginator\KeysetPaginator

The paginator to use.

$nextUrlPattern string

URL pattern for next page links. Must contain {@see \Yiisoft\Yii\DataView\Pagination\PaginationContext::URL_PLACEHOLDER}.

$previousUrlPattern string

URL pattern for previous page links. Must contain {@see \Yiisoft\Yii\DataView\Pagination\PaginationContext::URL_PLACEHOLDER}.

$accessibility boolean

Whether to add the aria-disabled, aria-label and, on disabled items, role="link" attributes automatically.

$translator \Yiisoft\Translator\TranslatorInterface|null

Translator used for the aria-label texts. When null, the English defaults are emitted as is.

$translationCategory string

Category used with the translator.

return self

New instance with the specified paginator and context.

                public static function create(
    KeysetPaginator $paginator,
    string $nextUrlPattern,
    string $previousUrlPattern,
    bool $accessibility = false,
    ?TranslatorInterface $translator = null,
    string $translationCategory = BaseListView::DEFAULT_TRANSLATION_CATEGORY,
): self {
    return self::widget()
        ->paginator($paginator)
        ->context(
            new PaginationContext(
                $nextUrlPattern,
                $previousUrlPattern,
                '',
                $accessibility,
                $translator,
                $translationCategory,
            ),
        );
}

            
disabledItemClass() public method

Sets the CSS class for disabled item elements.

public self disabledItemClass ( string|null $class )
$class string|null

The CSS class for disabled items.

return self

New instance with the specified disabled item class.

                public function disabledItemClass(?string $class): self
{
    $new = clone $this;
    $new->disabledItemClass = $class;
    return $new;
}

            
disabledLinkAttributes() public method

Sets HTML attributes for a disabled "previous"/"next" control, layered on top of {@see linkAttributes()}.

public self disabledLinkAttributes ( array $attributes )
$attributes array

HTML attributes for the span element of a disabled control.

return self

New instance with the specified disabled link attributes.

                public function disabledLinkAttributes(array $attributes): self
{
    $new = clone $this;
    $new->disabledLinkAttributes = $attributes;
    return $new;
}

            
disabledLinkClass() public method

Sets the CSS class for a disabled "previous"/"next" control.

A disabled control ("previous" on the first page, "next" on the last page) is rendered as a span element.

public self disabledLinkClass ( string|null $class )
$class string|null

The CSS class for the span element of a disabled control.

return self

New instance with the specified disabled link class.

                public function disabledLinkClass(?string $class): self
{
    $new = clone $this;
    $new->disabledLinkAttributes['class'] = [];
    Html::addCssClass($new->disabledLinkAttributes, $class);
    return $new;
}

            
getContext() protected method

Defined in: Yiisoft\Yii\DataView\Pagination\PaginationContextTrait::getContext()

Gets the current pagination context.

protected Yiisoft\Yii\DataView\Pagination\PaginationContext getContext ( )
return Yiisoft\Yii\DataView\Pagination\PaginationContext

The current pagination context.

throws LogicException

If the context has not been set.

                final protected function getContext(): PaginationContext
{
    if ($this->context === null) {
        throw new LogicException('Context is not set.');
    }
    return $this->context;
}

            
itemAttributes() public method

Sets the item element attributes.

public self itemAttributes ( array $attributes )
$attributes array

HTML attributes for the item elements.

return self

New instance with the specified item attributes.

                public function itemAttributes(array $attributes): self
{
    $new = clone $this;
    $new->itemAttributes = $attributes;
    return $new;
}

            
itemTag() public method

Sets the item tag name that wraps the "previous"/"next" control.

public self itemTag ( string|null $tag )
$tag string|null

The tag name for the item elements. Common values: 'li', 'div'. Use null to omit item containers.

return self

New instance with the specified item tag.

throws InvalidArgumentException

if tag name is empty.

                public function itemTag(?string $tag): self
{
    if ($tag === '') {
        throw new InvalidArgumentException('Tag name cannot be empty.');
    }
    $new = clone $this;
    $new->itemTag = $tag;
    return $new;
}

            
labelNext() public method

Sets the label for the next page link.

public self labelNext ( string|\Stringable $label )
$label string|\Stringable

The label for the next page link.

return self

New instance with the specified next label.

                public function labelNext(string|Stringable $label): self
{
    $new = clone $this;
    $new->labelNext = $label;
    return $new;
}

            
labelPrevious() public method

Sets the label for the previous page link.

public self labelPrevious ( string|\Stringable $label )
$label string|\Stringable

The label for the previous page link.

return self

New instance with the specified previous label.

                public function labelPrevious(string|Stringable $label): self
{
    $new = clone $this;
    $new->labelPrevious = $label;
    return $new;
}

            
linkAttributes() public method

Sets the link attributes.

public self linkAttributes ( array $attributes )
$attributes array

HTML attributes for the "previous"/"next" control.

return self

New instance with the specified link attributes.

                public function linkAttributes(array $attributes): self
{
    $new = clone $this;
    $new->linkAttributes = $attributes;
    return $new;
}

            
linkClass() public method

Set new link classes.

The classes are applied to the "previous"/"next" control — the a element, or the span element that replaces it when the control is disabled.

Multiple classes can be set by passing them as separate arguments. null values are filtered out automatically.

public self linkClass ( \BackedEnum|string|null $class )
$class \BackedEnum|string|null

One or more CSS class names to use. Pass null to skip a class.

                public function linkClass(BackedEnum|string|null ...$class): self
{
    $new = clone $this;
    $new->linkAttributes['class'] = [];
    Html::addCssClass($new->linkAttributes, $class);
    return $new;
}

            
listAttributes() public method

Sets the list element attributes.

public self listAttributes ( array $attributes )
$attributes array

HTML attributes for the list element.

return self

New instance with the specified list attributes.

                public function listAttributes(array $attributes): self
{
    $new = clone $this;
    $new->listAttributes = $attributes;
    return $new;
}

            
listTag() public method

Sets the list tag name.

public self listTag ( string|null $tag )
$tag string|null

The tag name for the list element. Common values: 'ul', 'div'. Use null to omit the list container.

return self

New instance with the specified list tag.

throws InvalidArgumentException

if tag name is empty.

                public function listTag(?string $tag): self
{
    if ($tag === '') {
        throw new InvalidArgumentException('Tag name cannot be empty.');
    }
    $new = clone $this;
    $new->listTag = $tag;
    return $new;
}

            
paginator() public method

Creates a new instance with the specified paginator.

public static paginator ( \Yiisoft\Data\Paginator\PaginatorInterface $paginator )
$paginator \Yiisoft\Data\Paginator\PaginatorInterface

The paginator to use.

return Yiisoft\Yii\DataView\Pagination\KeysetPagination

New instance with the specified paginator.

throws Yiisoft\Yii\DataView\Pagination\PaginatorNotSupportedException

If paginator is not a {@see \Yiisoft\Data\Paginator\KeysetPaginator}.

                public function paginator(PaginatorInterface $paginator): static
{
    /** @psalm-suppress DocblockTypeContradiction, NoValue */
    if (!$paginator instanceof KeysetPaginator) {
        throw new PaginatorNotSupportedException($paginator);
    }
    $new = clone $this;
    $new->paginator = $paginator;
    return $new;
}

            
render() public method

Renders the pagination controls.

public string render ( )
return string

The rendered HTML pagination controls.

throws Yiisoft\Yii\DataView\Pagination\PaginatorNotSetException

If paginator is not set.

                public function render(): string
{
    if (!$this->showOnSinglePage && !$this->getPaginator()->isPaginationRequired()) {
        return '';
    }
    $result = '';
    $context = $this->getContext();
    if ($this->containerTag !== null) {
        $containerAttributes = $this->containerAttributes;
        if (
            $context->accessibility
            && $this->ariaLabelNav !== null
            && !array_key_exists('aria-label', $containerAttributes)
        ) {
            $containerAttributes['aria-label'] = $context->translate($this->ariaLabelNav);
        }
        $result .= Html::openTag($this->containerTag, $containerAttributes) . "\n";
    }
    if ($this->listTag !== null) {
        $result .= Html::openTag($this->listTag, $this->listAttributes) . "\n";
    }
    $paginator = $this->getPaginator();
    $previousToken = $paginator->getPreviousToken();
    $nextToken = $paginator->getNextToken();
    $result .= $this->renderItem(
        $this->labelPrevious,
        $previousToken === null ? null : $context->createUrl($previousToken),
        $this->ariaLabelPrevious,
    )
        . "\n"
        . $this->renderItem(
            $this->labelNext,
            $nextToken === null ? null : $context->createUrl($nextToken),
            $this->ariaLabelNext,
        );
    if ($this->listTag !== null) {
        $result .= "\n" . Html::closeTag($this->listTag);
    }
    if ($this->containerTag !== null) {
        $result .= "\n" . Html::closeTag($this->containerTag);
    }
    return $result;
}

            
showOnSinglePage() public method

public self showOnSinglePage ( boolean $show = true )
$show boolean

                public function showOnSinglePage(bool $show = true): self
{
    $new = clone $this;
    $new->showOnSinglePage = $show;
    return $new;
}