xref: /plugin/combo/ComboStrap/RasterImageLink.php (revision c3437056399326d621a01da73b649707fbb0ae69) 
1<?php
2/**
3 * Copyright (c) 2020. ComboStrap, Inc. and its affiliates. All Rights Reserved.
4 *
5 * This source code is licensed under the GPL license found in the
6 * COPYING  file in the root directory of this source tree.
7 *
8 * @license  GPL 3 (https://www.gnu.org/licenses/gpl-3.0.en.html)
9 * @author   ComboStrap <support@combostrap.com>
10 *
11 */
12
13namespace ComboStrap;
14
15require_once(__DIR__ . '/MediaLink.php');
16require_once(__DIR__ . '/LazyLoad.php');
17require_once(__DIR__ . '/PluginUtility.php');
18
19/**
20 * Image
21 * This is the class that handles the
22 * raster image type of the dokuwiki {@link MediaLink}
23 *
24 * The real documentation can be found on the image page
25 * @link https://www.dokuwiki.org/images
26 *
27 * Doc:
28 * https://web.dev/optimize-cls/#images-without-dimensions
29 * https://web.dev/cls/
30 */
31class RasterImageLink extends ImageLink
32{
33
34    const CANONICAL = ImageRaster::CANONICAL;
35    const CONF_LAZY_LOADING_ENABLE = "rasterImageLazyLoadingEnable";
36    const CONF_LAZY_LOADING_ENABLE_DEFAULT = 1;
37
38    const RESPONSIVE_CLASS = "img-fluid";
39
40    const CONF_RESPONSIVE_IMAGE_MARGIN = "responsiveImageMargin";
41    const CONF_RETINA_SUPPORT_ENABLED = "retinaRasterImageEnable";
42    const LAZY_CLASS = "lazy-raster-combo";
43
44    const BREAKPOINTS =
45        array(
46            "xs" => 375,
47            "sm" => 576,
48            "md" => 768,
49            "lg" => 992
50        );
51
52
53    /**
54     * RasterImageLink constructor.
55     * @param ImageRaster $imageRaster
56     */
57    public function __construct($imageRaster)
58    {
59        parent::__construct($imageRaster);
60
61
62    }
63
64
65    /**
66     * Render a link
67     * Snippet derived from {@link \Doku_Renderer_xhtml::internalmedia()}
68     * A media can be a video also (Use
69     * @return string
70     */
71    public function renderMediaTag(): string
72    {
73        /**
74         * @var ImageRaster $image
75         */
76        $image = $this->getDefaultImage();
77        if ($image->exists()) {
78
79            $attributes = $image->getAttributes();
80
81            /**
82             * No dokuwiki type attribute
83             */
84            $attributes->removeComponentAttributeIfPresent(MediaLink::MEDIA_DOKUWIKI_TYPE);
85            $attributes->removeComponentAttributeIfPresent(MediaLink::DOKUWIKI_SRC);
86
87            /**
88             * Responsive image
89             * https://getbootstrap.com/docs/5.0/content/images/
90             * to apply max-width: 100%; and height: auto;
91             *
92             * Even if the resizing is requested by height,
93             * the height: auto on styling is needed to conserve the ratio
94             * while scaling down the screen
95             */
96            $attributes->addClassName(self::RESPONSIVE_CLASS);
97
98
99            /**
100             * width and height to give the dimension ratio
101             * They have an effect on the space reservation
102             * but not on responsive image at all
103             * To allow responsive height, the height style property is set at auto
104             * (ie img-fluid in bootstrap)
105             */
106            // The unit is not mandatory in HTML, this is expected to be CSS pixel
107            // https://html.spec.whatwg.org/multipage/embedded-content-other.html#attr-dim-height
108            // The HTML validator does not expect an unit otherwise it send an error
109            // https://validator.w3.org/
110            $htmlLengthUnit = "";
111
112            /**
113             * Height
114             * The logical height that the image should take on the page
115             *
116             * Note: The style is also set in {@link Dimension::processWidthAndHeight()}
117             *
118             */
119            $targetHeight = $image->getTargetHeight();
120            if (!empty($targetHeight)) {
121                $attributes->addHtmlAttributeValue("height", $targetHeight . $htmlLengthUnit);
122            }
123
124
125            /**
126             * Width
127             *
128             * We create a series of URL
129             * for different width and let the browser
130             * download the best one for:
131             *   * the actual container width
132             *   * the actual of screen resolution
133             *   * and the connection speed.
134             *
135             * The max-width value is set
136             */
137            $mediaWidthValue = $image->getIntrinsicWidth();
138            $srcValue = $image->getUrl();
139
140            /**
141             * Responsive image src set building
142             * We have chosen
143             *   * 375: Iphone6
144             *   * 768: Ipad
145             *   * 1024: Ipad Pro
146             *
147             */
148            // The image margin applied
149            $imageMargin = PluginUtility::getConfValue(self::CONF_RESPONSIVE_IMAGE_MARGIN, "20px");
150
151
152            /**
153             * Srcset and sizes for responsive image
154             * Width is mandatory for responsive image
155             * Ref https://developers.google.com/search/docs/advanced/guidelines/google-images#responsive-images
156             */
157            if (!empty($mediaWidthValue)) {
158
159                /**
160                 * The value of the target image
161                 */
162                $targetWidth = $image->getTargetWidth();
163                if (!empty($targetWidth)) {
164
165                    if (!empty($targetHeight)) {
166                        $image->checkLogicalRatioAgainstTargetRatio($targetWidth, $targetHeight);
167                    }
168                    $attributes->addHtmlAttributeValue("width", $targetWidth . $htmlLengthUnit);
169                }
170
171                /**
172                 * Continue
173                 */
174                $srcSet = "";
175                $sizes = "";
176
177                /**
178                 * Add smaller sizes
179                 */
180                foreach (self::BREAKPOINTS as $breakpointWidth) {
181
182                    if ($targetWidth > $breakpointWidth) {
183
184                        if (!empty($srcSet)) {
185                            $srcSet .= ", ";
186                            $sizes .= ", ";
187                        }
188                        $breakpointWidthMinusMargin = $breakpointWidth - $imageMargin;
189                        $xsmUrl = $image->getUrlForSrcSetAtBreakpoint($breakpointWidthMinusMargin);
190                        $srcSet .= "$xsmUrl {$breakpointWidthMinusMargin}w";
191                        $sizes .= $this->getSizes($breakpointWidth, $breakpointWidthMinusMargin);
192
193                    }
194
195                }
196
197                /**
198                 * Add the last size
199                 * If the target image is really small, srcset and sizes are empty
200                 */
201                if (!empty($srcSet)) {
202                    $srcSet .= ", ";
203                    $sizes .= ", ";
204                    $srcUrl = $image->getUrlForSrcSetAtBreakpoint($targetWidth);
205                    $srcSet .= "$srcUrl {$targetWidth}w";
206                    $sizes .= "{$targetWidth}px";
207                }
208
209                /**
210                 * Lazy load
211                 */
212                $lazyLoad = $this->getLazyLoad();
213                if ($lazyLoad) {
214
215                    /**
216                     * Snippet Lazy loading
217                     */
218                    LazyLoad::addLozadSnippet();
219                    PluginUtility::getSnippetManager()->attachJavascriptSnippetForBar("lozad-raster");
220                    $attributes->addClassName(self::LAZY_CLASS);
221                    $attributes->addClassName(LazyLoad::LAZY_CLASS);
222
223                    /**
224                     * A small image has no srcset
225                     *
226                     */
227                    if (!empty($srcSet)) {
228
229                        /**
230                         * !!!!! DON'T FOLLOW THIS ADVICE !!!!!!!!!
231                         * https://github.com/aFarkas/lazysizes/#modern-transparent-srcset-pattern
232                         * The transparent image has a fix dimension aspect ratio of 1x1 making
233                         * a bad reserved space for the image
234                         * We use a svg instead
235                         */
236                        $attributes->addHtmlAttributeValue("src", $srcValue);
237                        $attributes->addHtmlAttributeValue("srcset", LazyLoad::getPlaceholder($targetWidth, $targetHeight));
238                        /**
239                         * We use `data-sizes` and not `sizes`
240                         * because `sizes` without `srcset`
241                         * shows the broken image symbol
242                         * Javascript changes them at the same time
243                         */
244                        $attributes->addHtmlAttributeValue("data-sizes", $sizes);
245                        $attributes->addHtmlAttributeValue("data-srcset", $srcSet);
246
247                    } else {
248
249                        /**
250                         * Small image but there is no little improvement
251                         */
252                        $attributes->addHtmlAttributeValue("data-src", $srcValue);
253                        $attributes->addHtmlAttributeValue("src", LazyLoad::getPlaceholder($targetWidth, $targetHeight));
254
255                    }
256
257                    LazyLoad::addPlaceholderBackground($attributes);
258
259
260                } else {
261
262                    if (!empty($srcSet)) {
263                        $attributes->addHtmlAttributeValue("srcset", $srcSet);
264                        $attributes->addHtmlAttributeValue("sizes", $sizes);
265                    } else {
266                        $attributes->addHtmlAttributeValue("src", $srcValue);
267                    }
268
269                }
270
271            } else {
272
273                // No width, no responsive possibility
274                $lazyLoad = $this->getLazyLoad();
275                if ($lazyLoad) {
276
277                    LazyLoad::addPlaceholderBackground($attributes);
278                    $attributes->addHtmlAttributeValue("src", LazyLoad::getPlaceholder());
279                    $attributes->addHtmlAttributeValue("data-src", $srcValue);
280
281                }
282
283            }
284
285
286            /**
287             * Title (ie alt)
288             */
289            $attributes->addHtmlAttributeValueIfNotEmpty("alt", $image->getAltNotEmpty());
290
291            /**
292             * TODO: Side effect of the fact that we use the same attributes
293             * Title attribute of a media is the alt of an image
294             * And title should not be in an image tag
295             */
296            $attributes->removeAttributeIfPresent(TagAttributes::TITLE_KEY);
297
298            /**
299             * Old model where the src is parsed and the path
300             * is in the attributes
301             */
302            $attributes->removeAttributeIfPresent(PagePath::PROPERTY_NAME);
303
304            /**
305             * Create the img element
306             */
307            $htmlAttributes = $attributes->toHTMLAttributeString();
308            $imgHTML = '<img ' . $htmlAttributes . '/>';
309
310        } else {
311
312            $imgHTML = "<span class=\"text-danger\">The image ($this) does not exist</span>";
313
314        }
315
316        return $imgHTML;
317    }
318
319
320    public
321    function getLazyLoad()
322    {
323        $lazyLoad = parent::getLazyLoad();
324        if ($lazyLoad !== null) {
325            return $lazyLoad;
326        } else {
327            return PluginUtility::getConfValue(RasterImageLink::CONF_LAZY_LOADING_ENABLE, RasterImageLink::CONF_LAZY_LOADING_ENABLE_DEFAULT);
328        }
329    }
330
331    /**
332     * @param $screenWidth
333     * @param $imageWidth
334     * @return string sizes with a dpi correction if
335     */
336    private
337    function getSizes($screenWidth, $imageWidth): string
338    {
339
340        if ($this->getWithDpiCorrection()) {
341            $dpiBase = 96;
342            $sizes = "(max-width: {$screenWidth}px) and (min-resolution:" . (3 * $dpiBase) . "dpi) " . intval($imageWidth / 3) . "px";
343            $sizes .= ", (max-width: {$screenWidth}px) and (min-resolution:" . (2 * $dpiBase) . "dpi) " . intval($imageWidth / 2) . "px";
344            $sizes .= ", (max-width: {$screenWidth}px) and (min-resolution:" . (1 * $dpiBase) . "dpi) {$imageWidth}px";
345        } else {
346            $sizes = "(max-width: {$screenWidth}px) {$imageWidth}px";
347        }
348        return $sizes;
349    }
350
351    /**
352     * Return if the DPI correction is enabled or not for responsive image
353     *
354     * Mobile have a higher DPI and can then fit a bigger image on a smaller size.
355     *
356     * This can be disturbing when debugging responsive sizing image
357     * If you want also to use less bandwidth, this is also useful.
358     *
359     * @return bool
360     */
361    private
362    function getWithDpiCorrection(): bool
363    {
364        /**
365         * Support for retina means no DPI correction
366         */
367        $retinaEnabled = PluginUtility::getConfValue(self::CONF_RETINA_SUPPORT_ENABLED, 0);
368        return !$retinaEnabled;
369    }
370
371
372}
373