Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
0.00% covered (danger)
0.00%
0 / 14
0.00% covered (danger)
0.00%
0 / 9
 CRAP
0.00% covered (danger)
0.00%
0 / 1
Thumbnail
0.00% covered (danger)
0.00%
0 / 14
0.00% covered (danger)
0.00%
0 / 9
 110
0.00% covered (danger)
0.00%
0 / 1
 __construct
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getId
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getBackgroundImage
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getPlaceholderClass
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getAttributes
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 setId
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 2
 setBackgroundImage
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 2
 setPlaceholderClass
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 2
 setAttributes
0.00% covered (danger)
0.00%
0 / 3
0.00% covered (danger)
0.00%
0 / 1
 6
1<?php
2declare( strict_types = 1 );
3
4/**
5 * Thumbnail.php
6 *
7 * This file is part of the Codex design system, the official design system for Wikimedia projects.
8 * It contains the definition and implementation of the `Thumbnail` class, responsible for managing
9 * the behavior and properties of the corresponding component.
10 *
11 * @category Component
12 * @package  Codex\Component
13 * @since    0.1.0
14 * @author   Doğu Abaris <abaris@null.net>
15 * @license  https://www.gnu.org/copyleft/gpl.html GPL-2.0-or-later
16 * @link     https://doc.wikimedia.org/codex/main/ Codex Documentation
17 */
18
19namespace Wikimedia\Codex\Component;
20
21use Wikimedia\Codex\Contract\Component;
22use Wikimedia\Codex\Renderer\ThumbnailRenderer;
23
24/**
25 * Thumbnail
26 *
27 * @category Component
28 * @package  Codex\Component
29 * @since    0.1.0
30 * @author   Doğu Abaris <abaris@null.net>
31 * @license  https://www.gnu.org/copyleft/gpl.html GPL-2.0-or-later
32 * @link     https://doc.wikimedia.org/codex/main/ Codex Documentation
33 */
34class Thumbnail extends Component {
35    private string $id = '';
36
37    public function __construct(
38        ThumbnailRenderer $renderer,
39        private ?string $backgroundImage,
40        private ?string $placeholderClass,
41        private array $attributes
42    ) {
43        parent::__construct( $renderer );
44    }
45
46    /**
47     * Get the HTML ID for the thumbnail.
48     *
49     * This method returns the HTML `id` attribute value for the thumbnail element.
50     *
51     * @since 0.1.0
52     * @return string The ID for the thumbnail.
53     */
54    public function getId(): string {
55        return $this->id;
56    }
57
58    /**
59     * Get the background image URL for the thumbnail.
60     *
61     * This method returns the URL of the background image that will be displayed within the thumbnail.
62     * The image serves as a visual preview of the content.
63     *
64     * @since 0.1.0
65     * @return ?string The URL of the background image.
66     */
67    public function getBackgroundImage(): ?string {
68        return $this->backgroundImage;
69    }
70
71    /**
72     * Get the CSS class for the custom placeholder icon.
73     *
74     * This method returns the CSS class for the custom placeholder icon that will be displayed if
75     * the background image is not provided.
76     * The placeholder gives users a visual indication of where an image will appear.
77     *
78     * @since 0.1.0
79     * @return ?string The CSS class for the placeholder icon.
80     */
81    public function getPlaceholderClass(): ?string {
82        return $this->placeholderClass;
83    }
84
85    /**
86     * Retrieve additional HTML attributes for the thumbnail element.
87     *
88     * This method returns an associative array of custom HTML attributes that will be applied to the outer
89     * `<span>` element of the thumbnail. These attributes can be used to improve accessibility, enhance styling,
90     * or integrate with JavaScript functionality.
91     *
92     * @since 0.1.0
93     * @return array The additional attributes as an array.
94     */
95    public function getAttributes(): array {
96        return $this->attributes;
97    }
98
99    /**
100     * Set the Thumbnail HTML ID attribute.
101     *
102     * @deprecated Use setAttributes() to set the ID
103     * @since 0.1.0
104     * @param string $id The ID for the Thumbnail element.
105     * @return $this
106     */
107    public function setId( string $id ): self {
108        $this->id = $id;
109
110        return $this;
111    }
112
113    /**
114     * Set the background image for the thumbnail.
115     *
116     * This method specifies the URL of the background image that will be displayed
117     * within the thumbnail. The image serves as a visual preview of the content.
118     *
119     * Example usage:
120     *
121     *     $thumbnail->setBackgroundImage('https://example.com/image.jpg');
122     *
123     * @since 0.1.0
124     * @param string $backgroundImage The URL of the background image.
125     * @return $this Returns the Thumbnail instance for method chaining.
126     */
127    public function setBackgroundImage( string $backgroundImage ): self {
128        $this->backgroundImage = $backgroundImage;
129
130        return $this;
131    }
132
133    /**
134     * Set the CSS class for a custom placeholder icon.
135     *
136     * This method specifies a custom CSS class for a placeholder icon that will be displayed
137     * if the background image is not provided. The placeholder gives users a visual indication of where
138     * an image will appear.
139     *
140     * Example usage:
141     *
142     *     $thumbnail->setPlaceholderClass('custom-placeholder-icon');
143     *
144     * @since 0.1.0
145     * @param string $placeholderClass The CSS class for the placeholder icon.
146     * @return $this Returns the Thumbnail instance for method chaining.
147     */
148    public function setPlaceholderClass( string $placeholderClass ): self {
149        $this->placeholderClass = $placeholderClass;
150
151        return $this;
152    }
153
154    /**
155     * Set additional HTML attributes for the thumbnail element.
156     *
157     * This method allows custom HTML attributes to be added to the outer `<span>` element of the thumbnail,
158     * such as `id`, `data-*`, `aria-*`, or any other valid attributes. These attributes can be used to
159     * enhance accessibility or integrate with JavaScript.
160     *
161     * Example usage:
162     *
163     *     $thumbnail->setAttributes([
164     *         'id' => 'thumbnail-id',
165     *         'data-category' => 'images',
166     *     ]);
167     *
168     * @since 0.1.0
169     * @param array $attributes An associative array of HTML attributes.
170     * @return $this Returns the Thumbnail instance for method chaining.
171     */
172    public function setAttributes( array $attributes ): self {
173        foreach ( $attributes as $key => $value ) {
174            $this->attributes[$key] = $value;
175        }
176        return $this;
177    }
178}