0 follower

Final Class Yiisoft\Bootstrap5\Progress

InheritanceYiisoft\Bootstrap5\Progress » Yiisoft\Widget\Widget

Progress renders a bootstrap progress bar component.

For example,

<?= Progress::widget()->percent(60) ?>

//

<?= Progress::widget()
    ->backgroundColor(BackgroundColor::SUCCESS)
    ->percent(60)
    ->variant(ProgressVariant::ANIMATED_STRIPED)
?>

Public Methods

Hide inherited methods

Method Description Defined By
addAttributes() Adds a set of attributes. Yiisoft\Bootstrap5\Progress
addBarClass() Adds one or more CSS classes for the bar. Yiisoft\Bootstrap5\Progress
addClass() Adds one or more CSS classes to the existing classes. Yiisoft\Bootstrap5\Progress
addCssStyle() Adds a CSS style. Yiisoft\Bootstrap5\Progress
ariaLabel() Sets the ARIA label. Yiisoft\Bootstrap5\Progress
attribute() Sets attribute value. Yiisoft\Bootstrap5\Progress
attributes() Sets the HTML attributes. Yiisoft\Bootstrap5\Progress
backgroundColor() Sets the background color of the bar. Yiisoft\Bootstrap5\Progress
barAttributes() Sets the HTML attributes for the bar. Yiisoft\Bootstrap5\Progress
class() Replaces all existing CSS classes with the specified one(s). Yiisoft\Bootstrap5\Progress
content() Sets the content. Yiisoft\Bootstrap5\Progress
id() Sets the ID. Yiisoft\Bootstrap5\Progress
max() Sets the maximum value. Yiisoft\Bootstrap5\Progress
min() Sets the minimum value. Yiisoft\Bootstrap5\Progress
percent() Sets the percentage value for the bar. Yiisoft\Bootstrap5\Progress
render() Run the widget. Yiisoft\Bootstrap5\Progress
sizing() Sets the sizing variant. Yiisoft\Bootstrap5\Progress
stacked() Sets the bar to be stacked. Yiisoft\Bootstrap5\Progress
variant() Sets the variant. Yiisoft\Bootstrap5\Progress

Constants

Hide inherited constants

Constant Value Description Defined By
NAME 'progress' Yiisoft\Bootstrap5\Progress
PROGRESS_BAR 'progress-bar' Yiisoft\Bootstrap5\Progress

Method Details

Hide inherited methods

addAttributes() public method

Adds a set of attributes.

public self addAttributes ( array $attributes )
$attributes array

Attribute values indexed by attribute names. for example, ['id' => 'my-id'].

return self

A new instance with the specified attributes added.

Example usage: `php $progress->addAttributes(['data-id' => '123']); `

                public function addAttributes(array $attributes): self
{
    $new = clone $this;
    $new->attributes = [...$this->attributes, ...$attributes];
    return $new;
}

            
addBarClass() public method

Adds one or more CSS classes for the bar.

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

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

return self

A new instance with the specified CSS classes added to the bar.

Example usage: `php $progress->addBarClass('bg-success', null, 'progress-bar-striped'); `

                public function addBarClass(BackedEnum|string|null ...$class): self
{
    $new = clone $this;
    $new->barClasses = [...$this->barClasses, ...$class];
    return $new;
}

            
addClass() public method

Adds one or more CSS classes to the existing classes.

public self addClass ( \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 addClass(BackedEnum|string|null ...$class): self
{
    $new = clone $this;
    $new->cssClasses = [...$this->cssClasses, ...$class];
    return $new;
}

            
addCssStyle() public method

Adds a CSS style.

public self addCssStyle ( array|string $style, boolean $overwrite true )
$style array|string

The CSS style. If the value is an array, a space will separate the values. For example, ['color' => 'red', 'font-weight' => 'bold'] will be rendered as color: red; font-weight: bold;. If it is a string, it will be added as is, for example, color: red.

$overwrite boolean

Whether to overwrite existing styles with the same name. If false, the new value will be appended to the existing one.

return self

A new instance with the specified CSS style value added.

Example usage: `php $progress->addCssStyle('color: red');

// or $progress->addCssStyle(['color' => 'red', 'font-weight' => 'bold']); `

                public function addCssStyle(array|string $style, bool $overwrite = true): self
{
    $new = clone $this;
    Html::addCssStyle($new->attributes, $style, $overwrite);
    return $new;
}

            
ariaLabel() public method

Sets the ARIA label.

public self ariaLabel ( string $label )
$label string

The ARIA label.

return self

A new instance with the specified ARIA label.

                public function ariaLabel(string $label): self
{
    return $this->attribute('aria-label', $label);
}

            
attribute() public method

Sets attribute value.

public self attribute ( string $name, mixed $value )
$name string

The attribute name.

$value mixed

The attribute value.

return self

A new instance with the specified attribute set.

Example usage: `php $progress->attribute('data-id', '123'); `

                public function attribute(string $name, mixed $value): self
{
    $new = clone $this;
    $new->attributes[$name] = $value;
    return $new;
}

            
attributes() public method

Sets the HTML attributes.

public self attributes ( array $attributes )
$attributes array

Attribute values indexed by attribute names.

return self

A new instance with the specified attributes.

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

            
backgroundColor() public method

Sets the background color of the bar.

public self backgroundColor ( \Yiisoft\Bootstrap5\Utility\BackgroundColor $color )
$color \Yiisoft\Bootstrap5\Utility\BackgroundColor

The background color class to apply to the bar.

return self

A new instance with the specified background color applied.

                public function backgroundColor(BackgroundColor $color): self
{
    return $this->addBarClass($color);
}

            
barAttributes() public method

Sets the HTML attributes for the bar.

public self barAttributes ( array $attributes )
$attributes array

Attribute values indexed by attribute names.

return self

A new instance with the specified attributes for the bar.

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

            
class() public method

Replaces all existing CSS classes with the specified one(s).

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

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

return self

A new instance with the specified CSS classes set.

Example usage: `php $progress->class('custom-class', null, 'another-class', BackGroundColor::PRIMARY); `

                public function class(BackedEnum|string|null ...$class): self
{
    $new = clone $this;
    $new->cssClasses = $class;
    return $new;
}

            
content() public method

Sets the content.

public self content ( string $content )
$content string

The content to be displayed in the bar.

return self

A new instance with the specified content.

Example usage: `php $progress->content('Loading...'); `

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

            
id() public method

Sets the ID.

public self id ( boolean|string $id )
$id boolean|string

The ID of the component. If true, an ID will be generated automatically.

return self

A new instance with the specified ID.

Example usage: `php $progress->id('my-id'); `

                public function id(bool|string $id): self
{
    $new = clone $this;
    $new->id = $id;
    return $new;
}

            
max() public method

Sets the maximum value.

public self max ( float|integer $max )
$max float|integer

The maximum value. This value is used to calculate the progress percentage.

return self

A new instance with the specified maximum value.

Example usage: `php $progress->max(200); `

                public function max(int|float $max): self
{
    $new = clone $this;
    $new->max = $max;
    return $new;
}

            
min() public method

Sets the minimum value.

public self min ( float|integer $min )
$min float|integer

The minimum value. This value is used to calculate the progress percentage.

return self

A new instance with the specified minimum value.

Example usage: `php $progress->min(50); `

                public function min(int|float $min): self
{
    $new = clone $this;
    $new->min = $min;
    return $new;
}

            
percent() public method

Sets the percentage value for the bar.

public self percent ( float|integer $percent )
$percent float|integer

The percentage value. Must be greater than or equal to 0.

return self

A new instance with the specified percentage value.

Example usage: `php $progress->percent(60); `

throws LogicException

When percentage value is less than 0.

                public function percent(int|float $percent): self
{
    if ($percent < 0) {
        throw new LogicException(
            sprintf('"$percent" must be positive. %d given', $percent)
        );
    }
    $new = clone $this;
    $new->percent = $percent;
    return $new;
}

            
render() public method

Run the widget.

public string render ( )
return string

The HTML representation of the element.

                public function render(): string
{
    $attributes = $this->attributes;
    $classes = $attributes['class'] ?? null;
    unset($attributes['class']);
    if ($this->stacked) {
        $attributes['style'] = 'width: ' . $this->percent . '%';
    }
    return Div::tag()
        ->attributes($attributes)
        ->addClass(
            self::NAME,
            ...$this->cssClasses,
        )
        ->addClass($classes)
        ->attribute('role', 'progressbar')
        ->attribute('aria-valuenow', $this->percent)
        ->attribute('aria-valuemin', $this->min)
        ->attribute('aria-valuemax', $this->max)
        ->content(
            "\n",
            $this->renderBar(),
            "\n",
        )
        ->id($this->getId())
        ->encode(false)
        ->render();
}

            
sizing() public method

Sets the sizing variant.

public self sizing ( \Yiisoft\Bootstrap5\Utility\Sizing $size )
$size \Yiisoft\Bootstrap5\Utility\Sizing

The sizing variant to apply. This affects the width class of the bar.

return self

A new instance with the specified sizing variant.

Example usage: `php $progress->sizing(Sizing::WIDTH_75); `

                public function sizing(Sizing $size): self
{
    $new = clone $this;
    $new->sizing = true;
    return $new->addBarClass($size);
}

            
stacked() public method

Sets the bar to be stacked.

public self stacked ( )
return self

A new instance with the bar stacked.

Example usage: `php $progress->stacked(); `

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

            
variant() public method

Sets the variant.

public self variant ( \Yiisoft\Bootstrap5\ProgressVariant $variant )
$variant \Yiisoft\Bootstrap5\ProgressVariant

The variant to apply to the progress bar.

return self

A new instance with the specified variant.

Example usage: `php $progress->variant(ProgressVariant::ANIMATED_STRIPED); `

                public function variant(ProgressVariant $variant): self
{
    return $this->addBarClass($variant);
}